@agentcash/router 1.3.2 → 1.4.0

package/dist/index.cjs

@@ -1769,10 +1769,16 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
     const outputSchema = routeEntry.outputSchema ? toJSON(routeEntry.outputSchema) : void 0;
     if (inputSchema) {
       const config = {
+        method: routeEntry.method,
         bodyType: routeEntry.bodySchema ? "json" : void 0,
         inputSchema
       };
-      if (outputSchema) config.output = { schema: outputSchema, example: {} };
+      if (routeEntry.inputExample !== void 0) {
+        config.input = routeEntry.inputExample;
+      }
+      if (outputSchema && routeEntry.outputExample !== void 0) {
+        config.output = { schema: outputSchema, example: routeEntry.outputExample };
+      }
       extensions = declareDiscoveryExtension(config);
     }
   } catch (err) {
@@ -1891,6 +1897,46 @@ function fireProviderQuota(routeEntry, response, handlerResult, deps, pluginCtx)
   }
 }
 
+// src/validate-examples.ts
+function validateExamples(key, bodySchema, querySchema, outputSchema, inputExample, hasInputExample, outputExample, hasOutputExample) {
+  if (bodySchema && !hasInputExample) {
+    throw new Error(
+      `route '${key}': .body() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample body to advertise.`
+    );
+  }
+  if (querySchema && !hasInputExample) {
+    throw new Error(
+      `route '${key}': .query() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample query to advertise.`
+    );
+  }
+  if (outputSchema && !hasOutputExample) {
+    throw new Error(
+      `route '${key}': .output() requires a matching .outputExample() \u2014 the bazaar discovery extension needs a conforming sample response to advertise.`
+    );
+  }
+  const inputSchema = bodySchema ?? querySchema;
+  if (inputSchema && hasInputExample) {
+    const result = inputSchema.safeParse(inputExample);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `  \u2022 ${i.path.length ? i.path.join(".") : "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `route '${key}': .inputExample() does not satisfy ${bodySchema ? ".body()" : ".query()"} schema:
+${issues}`
+      );
+    }
+  }
+  if (outputSchema && hasOutputExample) {
+    const result = outputSchema.safeParse(outputExample);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `  \u2022 ${i.path.length ? i.path.join(".") : "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `route '${key}': .outputExample() does not satisfy .output() schema:
+${issues}`
+      );
+    }
+  }
+}
+
 // src/builder.ts
 var RouteBuilder = class {
   /** @internal */
@@ -1920,6 +1966,14 @@ var RouteBuilder = class {
   /** @internal */
   _outputSchema;
   /** @internal */
+  _inputExample = void 0;
+  /** @internal */
+  _hasInputExample = false;
+  /** @internal */
+  _outputExample = void 0;
+  /** @internal */
+  _hasOutputExample = false;
+  /** @internal */
   _description;
   /** @internal */
   _path;
@@ -2049,6 +2103,63 @@ var RouteBuilder = class {
     next._outputSchema = schema;
     return next;
   }
+  /**
+   * Provide a conforming example of the request input (body or query params).
+   *
+   * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
+   * `.handler()` overloads, and at route-registration time via Zod validation of the
+   * example against the schema. The example is embedded in the bazaar discovery extension
+   * so indexers can advertise a working sample call.
+   *
+   * @example
+   * ```ts
+   * router.route('search')
+   *   .paid('0.01')
+   *   .body(z.object({ q: z.string() }))
+   *   .inputExample({ q: 'hello world' })
+   *   .handler(async ({ body }) => { ... });
+   * ```
+   */
+  inputExample(example) {
+    const next = this.fork();
+    next._inputExample = example;
+    next._hasInputExample = true;
+    return next;
+  }
+  /**
+   * Provide a conforming example of the response output.
+   *
+   * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
+   * overloads, and at route-registration time via Zod validation of the example against
+   * the schema. The example is embedded in the bazaar discovery extension so indexers
+   * can advertise the response shape.
+   *
+   * Accepts any JSON value (objects, arrays, or primitives) — top-level array
+   * or primitive responses (e.g. `z.array(...)`) are supported alongside the
+   * common object case.
+   *
+   * @example
+   * ```ts
+   * router.route('search')
+   *   .paid('0.01')
+   *   .output(z.object({ results: z.array(z.string()) }))
+   *   .outputExample({ results: ['a', 'b'] })
+   *   .handler(async () => { ... });
+   *
+   * // Top-level array response
+   * router.route('chains')
+   *   .paid('0.01')
+   *   .output(z.array(z.object({ name: z.string() })))
+   *   .outputExample([{ name: 'Ethereum' }])
+   *   .handler(async () => { ... });
+   * ```
+   */
+  outputExample(example) {
+    const next = this.fork();
+    next._outputExample = example;
+    next._hasOutputExample = true;
+    return next;
+  }
   description(text) {
     const next = this.fork();
     next._description = text;
@@ -2093,12 +2204,26 @@ var RouteBuilder = class {
     next._validateFn = fn;
     return next;
   }
+  // -------------------------------------------------------------------------
+  // Terminal method
+  // -------------------------------------------------------------------------
   handler(fn) {
+    const handlerFn = fn;
     if (this._validateFn && !this._bodySchema) {
       throw new Error(
         `route '${this._key}': .validate() requires .body() \u2014 validation runs on parsed body`
       );
     }
+    validateExamples(
+      this._key,
+      this._bodySchema,
+      this._querySchema,
+      this._outputSchema,
+      this._inputExample,
+      this._hasInputExample,
+      this._outputExample,
+      this._hasOutputExample
+    );
     const entry = {
       key: this._key,
       authMode: this._authMode,
@@ -2108,6 +2233,8 @@ var RouteBuilder = class {
       bodySchema: this._bodySchema,
       querySchema: this._querySchema,
       outputSchema: this._outputSchema,
+      inputExample: this._hasInputExample ? this._inputExample : void 0,
+      outputExample: this._hasOutputExample ? this._outputExample : void 0,
       description: this._description,
       path: this._path,
       method: this._method,
@@ -2121,7 +2248,11 @@ var RouteBuilder = class {
       mppInfo: this._mppInfo
     };
     this._registry.register(entry);
-    return createRequestHandler(entry, fn, this._deps);
+    return createRequestHandler(
+      entry,
+      handlerFn,
+      this._deps
+    );
   }
 };
 

package/dist/index.d.cts

@@ -163,6 +163,11 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
 
 interface X402Server {
     initialize(): Promise<void>;
@@ -303,6 +308,25 @@ interface RouteEntry {
     bodySchema?: ZodType;
     querySchema?: ZodType;
     outputSchema?: ZodType;
+    /**
+     * Conforming example for the request input (body for body routes, query params for query routes).
+     * Required whenever `bodySchema` or `querySchema` is set. Must satisfy the corresponding schema —
+     * validated at route-registration time via the Zod schema.
+     *
+     * Emitted in the bazaar discovery extension so indexers can advertise a working sample call.
+     */
+    inputExample?: JsonObject;
+    /**
+     * Conforming example for the response output. Required whenever `outputSchema` is set.
+     * Must satisfy `outputSchema` — validated at route-registration time via the Zod schema.
+     *
+     * Accepts any JSON value (object, array, or primitive) to support top-level array or
+     * primitive response schemas.
+     *
+     * Emitted in the bazaar discovery extension. Without it the `output` block is dropped from
+     * the declaration entirely (the output schema alone cannot be exposed in bazaar without an example).
+     */
+    outputExample?: JsonValue;
     description?: string;
     path?: string;
     method: RouteMethod;
@@ -468,7 +492,33 @@ interface OrchestrateDeps {
 
 type True = true;
 type False = false;
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false> {
+/**
+ * Active request-input type at a builder position. Resolves to `TBody` when
+ * `.body()` has been called, `TQuery` when `.query()` has been called, and
+ * `never` when neither — making `.inputExample()` unusable before a schema
+ * is set (the literal won't assign to `never`).
+ */
+type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extends [undefined] ? never : TQuery : TBody;
+/**
+ * The handler argument type. Narrows to the real handler signature when the
+ * builder state is valid, and to a descriptive error object when it isn't —
+ * the mismatch surfaces as a TS type error at the `.handler(...)` call site
+ * with the `__missing` string as the contextual hint.
+ *
+ * Encoded as a conditional argument rather than overload `this:` constraints
+ * because TypeScript doesn't reliably gate overload selection on `this` for
+ * generic classes (structurally identical instance types collapse).
+ */
+type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, NeedsInputExample extends boolean, NeedsOutputExample 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';
+} : NeedsInputExample extends true ? {
+    __missing: 'Call .inputExample(sample) — .body()/.query() routes must advertise a conforming request example for bazaar discovery';
+} : NeedsOutputExample extends true ? {
+    __missing: 'Call .outputExample(sample) — .output() routes must advertise a conforming response example for bazaar discovery';
+} : (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown> : {
+    __missing: 'Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()';
+};
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, NeedsInputExample extends boolean = false, NeedsOutputExample extends boolean = false> {
     /** @internal */ readonly _key: string;
     /** @internal */ readonly _registry: RouteRegistry;
     /** @internal */ readonly _deps: OrchestrateDeps;
@@ -482,6 +532,10 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @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';
@@ -492,10 +546,10 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _mppInfo: MppProtocolInfo | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
-    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
         maxPrice?: string;
-    }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
     paid(pricing: {
         field: string;
         tiers: Record<string, {
@@ -503,14 +557,61 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
             label?: string;
         }>;
         default?: string;
-    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
-    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
-    unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
+    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
+    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
+    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
     provider(name: string, config?: ProviderConfig): this;
-    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, HasAuth, NeedsBody, True>;
-    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, HasAuth, NeedsBody, HasBody>;
-    output(schema: ZodType): this;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True, True, NeedsOutputExample>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody, True, NeedsOutputExample>;
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, NeedsInputExample, True>;
+    /**
+     * Provide a conforming example of the request input (body or query params).
+     *
+     * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
+     * `.handler()` overloads, and at route-registration time via Zod validation of the
+     * example against the schema. The example is embedded in the bazaar discovery extension
+     * so indexers can advertise a working sample call.
+     *
+     * @example
+     * ```ts
+     * router.route('search')
+     *   .paid('0.01')
+     *   .body(z.object({ q: z.string() }))
+     *   .inputExample({ q: 'hello world' })
+     *   .handler(async ({ body }) => { ... });
+     * ```
+     */
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, False, NeedsOutputExample>;
+    /**
+     * Provide a conforming example of the response output.
+     *
+     * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
+     * overloads, and at route-registration time via Zod validation of the example against
+     * the schema. The example is embedded in the bazaar discovery extension so indexers
+     * can advertise the response shape.
+     *
+     * Accepts any JSON value (objects, arrays, or primitives) — top-level array
+     * or primitive responses (e.g. `z.array(...)`) are supported alongside the
+     * common object case.
+     *
+     * @example
+     * ```ts
+     * router.route('search')
+     *   .paid('0.01')
+     *   .output(z.object({ results: z.array(z.string()) }))
+     *   .outputExample({ results: ['a', 'b'] })
+     *   .handler(async () => { ... });
+     *
+     * // Top-level array response
+     * router.route('chains')
+     *   .paid('0.01')
+     *   .output(z.array(z.object({ name: z.string() })))
+     *   .outputExample([{ name: 'Ethereum' }])
+     *   .handler(async () => { ... });
+     * ```
+     */
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, False>;
     description(text: string): this;
     path(p: string): this;
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
@@ -535,11 +636,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
      *   .handler(async ({ body }) => { ... });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, HasAuth, NeedsBody, HasBody>;
-    handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
-    handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
-    handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
-    handler(this: RouteBuilder<TBody, TQuery, True, True, True>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
+    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>): (request: NextRequest) => Promise<Response>;
 }
 
 interface MonitorEntry {
@@ -551,7 +649,7 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, true, false, false, false, false> : RouteBuilder<undefined, undefined, undefined, false, false, false, false, false>;
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;

package/dist/index.d.ts

@@ -163,6 +163,11 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
 
 interface X402Server {
     initialize(): Promise<void>;
@@ -303,6 +308,25 @@ interface RouteEntry {
     bodySchema?: ZodType;
     querySchema?: ZodType;
     outputSchema?: ZodType;
+    /**
+     * Conforming example for the request input (body for body routes, query params for query routes).
+     * Required whenever `bodySchema` or `querySchema` is set. Must satisfy the corresponding schema —
+     * validated at route-registration time via the Zod schema.
+     *
+     * Emitted in the bazaar discovery extension so indexers can advertise a working sample call.
+     */
+    inputExample?: JsonObject;
+    /**
+     * Conforming example for the response output. Required whenever `outputSchema` is set.
+     * Must satisfy `outputSchema` — validated at route-registration time via the Zod schema.
+     *
+     * Accepts any JSON value (object, array, or primitive) to support top-level array or
+     * primitive response schemas.
+     *
+     * Emitted in the bazaar discovery extension. Without it the `output` block is dropped from
+     * the declaration entirely (the output schema alone cannot be exposed in bazaar without an example).
+     */
+    outputExample?: JsonValue;
     description?: string;
     path?: string;
     method: RouteMethod;
@@ -468,7 +492,33 @@ interface OrchestrateDeps {
 
 type True = true;
 type False = false;
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false> {
+/**
+ * Active request-input type at a builder position. Resolves to `TBody` when
+ * `.body()` has been called, `TQuery` when `.query()` has been called, and
+ * `never` when neither — making `.inputExample()` unusable before a schema
+ * is set (the literal won't assign to `never`).
+ */
+type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extends [undefined] ? never : TQuery : TBody;
+/**
+ * The handler argument type. Narrows to the real handler signature when the
+ * builder state is valid, and to a descriptive error object when it isn't —
+ * the mismatch surfaces as a TS type error at the `.handler(...)` call site
+ * with the `__missing` string as the contextual hint.
+ *
+ * Encoded as a conditional argument rather than overload `this:` constraints
+ * because TypeScript doesn't reliably gate overload selection on `this` for
+ * generic classes (structurally identical instance types collapse).
+ */
+type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, NeedsInputExample extends boolean, NeedsOutputExample 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';
+} : NeedsInputExample extends true ? {
+    __missing: 'Call .inputExample(sample) — .body()/.query() routes must advertise a conforming request example for bazaar discovery';
+} : NeedsOutputExample extends true ? {
+    __missing: 'Call .outputExample(sample) — .output() routes must advertise a conforming response example for bazaar discovery';
+} : (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown> : {
+    __missing: 'Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()';
+};
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, NeedsInputExample extends boolean = false, NeedsOutputExample extends boolean = false> {
     /** @internal */ readonly _key: string;
     /** @internal */ readonly _registry: RouteRegistry;
     /** @internal */ readonly _deps: OrchestrateDeps;
@@ -482,6 +532,10 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @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';
@@ -492,10 +546,10 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _mppInfo: MppProtocolInfo | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
-    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
         maxPrice?: string;
-    }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
     paid(pricing: {
         field: string;
         tiers: Record<string, {
@@ -503,14 +557,61 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
             label?: string;
         }>;
         default?: string;
-    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
-    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
-    unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
+    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
+    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
+    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
     provider(name: string, config?: ProviderConfig): this;
-    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, HasAuth, NeedsBody, True>;
-    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, HasAuth, NeedsBody, HasBody>;
-    output(schema: ZodType): this;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True, True, NeedsOutputExample>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody, True, NeedsOutputExample>;
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, NeedsInputExample, True>;
+    /**
+     * Provide a conforming example of the request input (body or query params).
+     *
+     * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
+     * `.handler()` overloads, and at route-registration time via Zod validation of the
+     * example against the schema. The example is embedded in the bazaar discovery extension
+     * so indexers can advertise a working sample call.
+     *
+     * @example
+     * ```ts
+     * router.route('search')
+     *   .paid('0.01')
+     *   .body(z.object({ q: z.string() }))
+     *   .inputExample({ q: 'hello world' })
+     *   .handler(async ({ body }) => { ... });
+     * ```
+     */
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, False, NeedsOutputExample>;
+    /**
+     * Provide a conforming example of the response output.
+     *
+     * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
+     * overloads, and at route-registration time via Zod validation of the example against
+     * the schema. The example is embedded in the bazaar discovery extension so indexers
+     * can advertise the response shape.
+     *
+     * Accepts any JSON value (objects, arrays, or primitives) — top-level array
+     * or primitive responses (e.g. `z.array(...)`) are supported alongside the
+     * common object case.
+     *
+     * @example
+     * ```ts
+     * router.route('search')
+     *   .paid('0.01')
+     *   .output(z.object({ results: z.array(z.string()) }))
+     *   .outputExample({ results: ['a', 'b'] })
+     *   .handler(async () => { ... });
+     *
+     * // Top-level array response
+     * router.route('chains')
+     *   .paid('0.01')
+     *   .output(z.array(z.object({ name: z.string() })))
+     *   .outputExample([{ name: 'Ethereum' }])
+     *   .handler(async () => { ... });
+     * ```
+     */
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, False>;
     description(text: string): this;
     path(p: string): this;
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
@@ -535,11 +636,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
      *   .handler(async ({ body }) => { ... });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, HasAuth, NeedsBody, HasBody>;
-    handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
-    handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
-    handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
-    handler(this: RouteBuilder<TBody, TQuery, True, True, True>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
+    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>): (request: NextRequest) => Promise<Response>;
 }
 
 interface MonitorEntry {
@@ -551,7 +649,7 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, true, false, false, false, false> : RouteBuilder<undefined, undefined, undefined, false, false, false, false, false>;
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;

package/dist/index.js

@@ -1730,10 +1730,16 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
     const outputSchema = routeEntry.outputSchema ? toJSON(routeEntry.outputSchema) : void 0;
     if (inputSchema) {
       const config = {
+        method: routeEntry.method,
         bodyType: routeEntry.bodySchema ? "json" : void 0,
         inputSchema
       };
-      if (outputSchema) config.output = { schema: outputSchema, example: {} };
+      if (routeEntry.inputExample !== void 0) {
+        config.input = routeEntry.inputExample;
+      }
+      if (outputSchema && routeEntry.outputExample !== void 0) {
+        config.output = { schema: outputSchema, example: routeEntry.outputExample };
+      }
       extensions = declareDiscoveryExtension(config);
     }
   } catch (err) {
@@ -1852,6 +1858,46 @@ function fireProviderQuota(routeEntry, response, handlerResult, deps, pluginCtx)
   }
 }
 
+// src/validate-examples.ts
+function validateExamples(key, bodySchema, querySchema, outputSchema, inputExample, hasInputExample, outputExample, hasOutputExample) {
+  if (bodySchema && !hasInputExample) {
+    throw new Error(
+      `route '${key}': .body() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample body to advertise.`
+    );
+  }
+  if (querySchema && !hasInputExample) {
+    throw new Error(
+      `route '${key}': .query() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample query to advertise.`
+    );
+  }
+  if (outputSchema && !hasOutputExample) {
+    throw new Error(
+      `route '${key}': .output() requires a matching .outputExample() \u2014 the bazaar discovery extension needs a conforming sample response to advertise.`
+    );
+  }
+  const inputSchema = bodySchema ?? querySchema;
+  if (inputSchema && hasInputExample) {
+    const result = inputSchema.safeParse(inputExample);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `  \u2022 ${i.path.length ? i.path.join(".") : "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `route '${key}': .inputExample() does not satisfy ${bodySchema ? ".body()" : ".query()"} schema:
+${issues}`
+      );
+    }
+  }
+  if (outputSchema && hasOutputExample) {
+    const result = outputSchema.safeParse(outputExample);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `  \u2022 ${i.path.length ? i.path.join(".") : "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `route '${key}': .outputExample() does not satisfy .output() schema:
+${issues}`
+      );
+    }
+  }
+}
+
 // src/builder.ts
 var RouteBuilder = class {
   /** @internal */
@@ -1881,6 +1927,14 @@ var RouteBuilder = class {
   /** @internal */
   _outputSchema;
   /** @internal */
+  _inputExample = void 0;
+  /** @internal */
+  _hasInputExample = false;
+  /** @internal */
+  _outputExample = void 0;
+  /** @internal */
+  _hasOutputExample = false;
+  /** @internal */
   _description;
   /** @internal */
   _path;
@@ -2010,6 +2064,63 @@ var RouteBuilder = class {
     next._outputSchema = schema;
     return next;
   }
+  /**
+   * Provide a conforming example of the request input (body or query params).
+   *
+   * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
+   * `.handler()` overloads, and at route-registration time via Zod validation of the
+   * example against the schema. The example is embedded in the bazaar discovery extension
+   * so indexers can advertise a working sample call.
+   *
+   * @example
+   * ```ts
+   * router.route('search')
+   *   .paid('0.01')
+   *   .body(z.object({ q: z.string() }))
+   *   .inputExample({ q: 'hello world' })
+   *   .handler(async ({ body }) => { ... });
+   * ```
+   */
+  inputExample(example) {
+    const next = this.fork();
+    next._inputExample = example;
+    next._hasInputExample = true;
+    return next;
+  }
+  /**
+   * Provide a conforming example of the response output.
+   *
+   * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
+   * overloads, and at route-registration time via Zod validation of the example against
+   * the schema. The example is embedded in the bazaar discovery extension so indexers
+   * can advertise the response shape.
+   *
+   * Accepts any JSON value (objects, arrays, or primitives) — top-level array
+   * or primitive responses (e.g. `z.array(...)`) are supported alongside the
+   * common object case.
+   *
+   * @example
+   * ```ts
+   * router.route('search')
+   *   .paid('0.01')
+   *   .output(z.object({ results: z.array(z.string()) }))
+   *   .outputExample({ results: ['a', 'b'] })
+   *   .handler(async () => { ... });
+   *
+   * // Top-level array response
+   * router.route('chains')
+   *   .paid('0.01')
+   *   .output(z.array(z.object({ name: z.string() })))
+   *   .outputExample([{ name: 'Ethereum' }])
+   *   .handler(async () => { ... });
+   * ```
+   */
+  outputExample(example) {
+    const next = this.fork();
+    next._outputExample = example;
+    next._hasOutputExample = true;
+    return next;
+  }
   description(text) {
     const next = this.fork();
     next._description = text;
@@ -2054,12 +2165,26 @@ var RouteBuilder = class {
     next._validateFn = fn;
     return next;
   }
+  // -------------------------------------------------------------------------
+  // Terminal method
+  // -------------------------------------------------------------------------
   handler(fn) {
+    const handlerFn = fn;
     if (this._validateFn && !this._bodySchema) {
       throw new Error(
         `route '${this._key}': .validate() requires .body() \u2014 validation runs on parsed body`
       );
     }
+    validateExamples(
+      this._key,
+      this._bodySchema,
+      this._querySchema,
+      this._outputSchema,
+      this._inputExample,
+      this._hasInputExample,
+      this._outputExample,
+      this._hasOutputExample
+    );
     const entry = {
       key: this._key,
       authMode: this._authMode,
@@ -2069,6 +2194,8 @@ var RouteBuilder = class {
       bodySchema: this._bodySchema,
       querySchema: this._querySchema,
       outputSchema: this._outputSchema,
+      inputExample: this._hasInputExample ? this._inputExample : void 0,
+      outputExample: this._hasOutputExample ? this._outputExample : void 0,
       description: this._description,
       path: this._path,
       method: this._method,
@@ -2082,7 +2209,11 @@ var RouteBuilder = class {
       mppInfo: this._mppInfo
     };
     this._registry.register(entry);
-    return createRequestHandler(entry, fn, this._deps);
+    return createRequestHandler(
+      entry,
+      handlerFn,
+      this._deps
+    );
   }
 };
 

package/package.json

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