@agentcash/telemetry 0.3.0

package/README.md

@@ -0,0 +1,128 @@
+# @merit-systems/x402-server-telemetry
+
+[![npm](https://img.shields.io/npm/v/@merit-systems/x402-server-telemetry)](https://www.npmjs.com/package/@merit-systems/x402-server-telemetry)
+
+Shared telemetry for Merit Systems x402 servers. Extracts identity headers, logs invocations to ClickHouse, and auto-extracts verified wallets from x402 payments and SIWX auth.
+
+[Telemetry spec](docs/telemetry-spec.md) | [npm](https://www.npmjs.com/package/@merit-systems/x402-server-telemetry) | [GitHub](https://github.com/Merit-Systems/x402-server-telemetry)
+
+## Install
+
+```bash
+npm install @merit-systems/x402-server-telemetry @clickhouse/client
+```
+
+## Quick start
+
+```typescript
+// lib/telemetry.ts (or wherever your route wrappers live)
+import { initTelemetry, withTelemetry } from '@merit-systems/x402-server-telemetry';
+
+initTelemetry({
+  clickhouse: {
+    url: process.env.TELEM_CLICKHOUSE_URL!,
+    database: process.env.TELEM_CLICKHOUSE_DATABASE,
+    username: process.env.TELEM_CLICKHOUSE_USERNAME,
+    password: process.env.TELEM_CLICKHOUSE_PASSWORD,
+  },
+  verify: true, // optional — pings ClickHouse on startup, logs success/failure
+});
+
+export { withTelemetry };
+```
+
+```typescript
+// app/api/example/route.ts
+import { withTelemetry } from '@/lib/telemetry';
+
+export const POST = withTelemetry(async (request, ctx) => {
+  return NextResponse.json(await doWork(request));
+});
+```
+
+## Three entrypoints
+
+### Core (`@merit-systems/x402-server-telemetry`)
+
+Requires: `@clickhouse/client`, `next`
+
+```typescript
+import { initTelemetry, withTelemetry } from '@merit-systems/x402-server-telemetry';
+```
+
+- `initTelemetry(config)` — synchronous, call once at module level. Pass `verify: true` to ping ClickHouse on startup (fire-and-forget, never blocks)
+- `withTelemetry(handler)` — wrap any Next.js route handler
+- `extractVerifiedWallet(headers)` — extract wallet from x402 payment headers
+
+### SIWX (`@merit-systems/x402-server-telemetry/siwx`)
+
+Requires: `@x402/extensions`, `@x402/core`
+
+```typescript
+import { withSiwxTelemetry } from '@merit-systems/x402-server-telemetry/siwx';
+
+export const GET = withSiwxTelemetry(async (request, ctx) => {
+  // ctx.verifiedWallet is guaranteed to be set
+  return NextResponse.json(await getJobs(ctx.verifiedWallet));
+});
+```
+
+### Route Builder (`@merit-systems/x402-server-telemetry/builder`)
+
+Requires: `@x402/next`, `zod` (^4), `@x402/extensions`
+
+```typescript
+import { createRouteBuilder } from '@merit-systems/x402-server-telemetry/builder';
+
+const route = createRouteBuilder({ x402Server });
+
+export const POST = route
+  .price('0.05', 'base:8453')
+  .body(searchSchema)
+  .handler(async ({ body }) => searchPeople(body.query));
+```
+
+## Next.js integration footguns
+
+### `@clickhouse/client` must be externalized
+
+The ClickHouse client uses Node.js native APIs that break when bundled by Next.js. Add to your `next.config`:
+
+```typescript
+const nextConfig: NextConfig = {
+  serverExternalPackages: ['@clickhouse/client'],
+};
+```
+
+### Do NOT call `initTelemetry` in `instrumentation.ts`
+
+On Vercel serverless, `instrumentation.ts` runs in a **separate module scope** from route handlers. Singletons set there are invisible to your handlers.
+
+Call `initTelemetry()` in the same module that imports your route wrappers:
+
+```typescript
+// lib/telemetry.ts — CORRECT
+import { initTelemetry, withTelemetry } from '@merit-systems/x402-server-telemetry';
+initTelemetry({ clickhouse: { ... } });
+export { withTelemetry };
+```
+
+```typescript
+// instrumentation.ts — WRONG: singleton won't be shared with handlers
+import { initTelemetry } from '@merit-systems/x402-server-telemetry';
+export async function register() {
+  initTelemetry({ clickhouse: { ... } }); // handlers can't see this
+}
+```
+
+### Subpath exports isolate heavy deps
+
+The `/siwx` and `/builder` entrypoints have additional peer dependencies. If you only use the core `withTelemetry`, you don't need `zod`, `@x402/next`, or `@x402/extensions` installed.
+
+### After updating, commit both `package.json` and lockfile
+
+`pnpm update @merit-systems/x402-server-telemetry` bumps the version specifier in **both** `package.json` and `pnpm-lock.yaml`. Vercel's `frozen-lockfile` mode will reject deploys if only the lockfile is committed. Always:
+
+```bash
+git add package.json pnpm-lock.yaml
+```

package/dist/builder.d.mts

@@ -0,0 +1,58 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ZodType } from 'zod';
+import { a as TelemetryContext } from './types-Bl8IwXin.mjs';
+
+/**
+ * Convenience route builder that composes telemetry + validation + x402 wrapping.
+ * This is optional — servers can use withTelemetry directly.
+ *
+ * Import from '@agentcash/telemetry/builder'.
+ * Requires peer deps: @x402/next, zod (^4), @x402/extensions
+ */
+
+declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+type AcceptsOption = {
+    amount: string;
+    network: string;
+    asset?: string;
+};
+type BuilderConfig<TBody = unknown, TQuery = unknown, TOutput = unknown> = {
+    accepts: AcceptsOption[];
+    bodySchema?: ZodType<TBody>;
+    querySchema?: ZodType<TQuery>;
+    outputSchema?: ZodType<TOutput>;
+    outputExample?: TOutput;
+    description?: string;
+};
+type HandlerContext<TBody, TQuery> = {
+    body: TBody;
+    query: TQuery;
+    request: NextRequest;
+    telemetry: TelemetryContext;
+};
+type HandlerFn<TBody, TQuery, TResponse> = (ctx: HandlerContext<TBody, TQuery>) => Promise<TResponse>;
+interface RouteBuilderOptions {
+    /** The x402 resource server instance (from @x402/core/server). Required when using .price(). */
+    x402Server?: unknown;
+}
+declare class RouteBuilder<TBody = unknown, TQuery = unknown, TOutput = unknown> {
+    private config;
+    private options;
+    constructor(config?: Partial<BuilderConfig<TBody, TQuery, TOutput>>, options?: RouteBuilderOptions);
+    price(amount: string, network: string, asset?: string): RouteBuilder<TBody, TQuery, TOutput>;
+    accepts(options: AcceptsOption[]): RouteBuilder<TBody, TQuery, TOutput>;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput>;
+    output<T>(schema: ZodType<T>, example?: T): RouteBuilder<TBody, TQuery, T>;
+    description(text: string): RouteBuilder<TBody, TQuery, TOutput>;
+    handler<TResponse>(fn: HandlerFn<TBody, TQuery, TResponse>): (request: NextRequest) => Promise<NextResponse>;
+}
+/**
+ * Create a new route builder instance.
+ */
+declare function createRouteBuilder(options?: RouteBuilderOptions): RouteBuilder<unknown, unknown, unknown>;
+
+export { HttpError, type RouteBuilderOptions, createRouteBuilder };

package/dist/builder.d.ts

@@ -0,0 +1,58 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ZodType } from 'zod';
+import { a as TelemetryContext } from './types-Bl8IwXin.js';
+
+/**
+ * Convenience route builder that composes telemetry + validation + x402 wrapping.
+ * This is optional — servers can use withTelemetry directly.
+ *
+ * Import from '@agentcash/telemetry/builder'.
+ * Requires peer deps: @x402/next, zod (^4), @x402/extensions
+ */
+
+declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+type AcceptsOption = {
+    amount: string;
+    network: string;
+    asset?: string;
+};
+type BuilderConfig<TBody = unknown, TQuery = unknown, TOutput = unknown> = {
+    accepts: AcceptsOption[];
+    bodySchema?: ZodType<TBody>;
+    querySchema?: ZodType<TQuery>;
+    outputSchema?: ZodType<TOutput>;
+    outputExample?: TOutput;
+    description?: string;
+};
+type HandlerContext<TBody, TQuery> = {
+    body: TBody;
+    query: TQuery;
+    request: NextRequest;
+    telemetry: TelemetryContext;
+};
+type HandlerFn<TBody, TQuery, TResponse> = (ctx: HandlerContext<TBody, TQuery>) => Promise<TResponse>;
+interface RouteBuilderOptions {
+    /** The x402 resource server instance (from @x402/core/server). Required when using .price(). */
+    x402Server?: unknown;
+}
+declare class RouteBuilder<TBody = unknown, TQuery = unknown, TOutput = unknown> {
+    private config;
+    private options;
+    constructor(config?: Partial<BuilderConfig<TBody, TQuery, TOutput>>, options?: RouteBuilderOptions);
+    price(amount: string, network: string, asset?: string): RouteBuilder<TBody, TQuery, TOutput>;
+    accepts(options: AcceptsOption[]): RouteBuilder<TBody, TQuery, TOutput>;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput>;
+    output<T>(schema: ZodType<T>, example?: T): RouteBuilder<TBody, TQuery, T>;
+    description(text: string): RouteBuilder<TBody, TQuery, TOutput>;
+    handler<TResponse>(fn: HandlerFn<TBody, TQuery, TResponse>): (request: NextRequest) => Promise<NextResponse>;
+}
+/**
+ * Create a new route builder instance.
+ */
+declare function createRouteBuilder(options?: RouteBuilderOptions): RouteBuilder<unknown, unknown, unknown>;
+
+export { HttpError, type RouteBuilderOptions, createRouteBuilder };

package/dist/builder.js

@@ -0,0 +1,218 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+
+
+var _chunkGE7VBMQPjs = require('./chunk-GE7VBMQP.js');
+require('./chunk-P63MLKU3.js');
+
+// src/route-builder.ts
+var _server = require('next/server');
+var _next = require('@x402/next');
+var _zod = require('zod');
+var _bazaar = require('@x402/extensions/bazaar');
+var HttpError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "HttpError";
+  }
+};
+function formatValidationError(error) {
+  const issues = error.issues;
+  if (issues.length === 0) return "Validation failed";
+  if (issues.length === 1) {
+    const issue = issues[0];
+    const path = issue.path.join(".");
+    const field = path || "request";
+    if (issue.message) return `${field}: ${issue.message}`;
+    return `${field}: Invalid value`;
+  }
+  const errors = issues.map((issue) => {
+    const path = issue.path.join(".");
+    const field = path || "request";
+    return issue.message ? `${field}: ${issue.message}` : `${field}: Invalid`;
+  });
+  return `Validation failed: ${errors.join("; ")}`;
+}
+var RouteBuilder = class _RouteBuilder {
+  
+  
+  constructor(config, options) {
+    this.config = { accepts: [], ...config };
+    this.options = _nullishCoalesce(options, () => ( {}));
+  }
+  price(amount, network, asset) {
+    return new _RouteBuilder(
+      { ...this.config, accepts: [{ amount, network, asset }] },
+      this.options
+    );
+  }
+  accepts(options) {
+    return new _RouteBuilder(
+      { ...this.config, accepts: options },
+      this.options
+    );
+  }
+  body(schema) {
+    return new _RouteBuilder(
+      { ...this.config, bodySchema: schema },
+      this.options
+    );
+  }
+  query(schema) {
+    return new _RouteBuilder(
+      { ...this.config, querySchema: schema },
+      this.options
+    );
+  }
+  output(schema, example) {
+    return new _RouteBuilder(
+      {
+        ...this.config,
+        outputSchema: schema,
+        outputExample: example
+      },
+      this.options
+    );
+  }
+  description(text) {
+    return new _RouteBuilder(
+      { ...this.config, description: text },
+      this.options
+    );
+  }
+  handler(fn) {
+    const { accepts, bodySchema, querySchema, outputSchema, outputExample, description } = this.config;
+    const coreHandler = async (request) => {
+      const meta = _chunkGE7VBMQPjs.extractRequestMeta.call(void 0, request);
+      const ctx = _chunkGE7VBMQPjs.buildTelemetryContext.call(void 0, meta);
+      const log = (status, responseBody, resp) => {
+        _chunkGE7VBMQPjs.recordInvocation.call(void 0, meta, requestBodyString, {
+          status,
+          body: responseBody,
+          headers: JSON.stringify(Object.fromEntries(resp.headers.entries())),
+          contentType: _nullishCoalesce(resp.headers.get("content-type"), () => ( null))
+        });
+      };
+      let body = void 0;
+      let query = void 0;
+      let requestBodyString = null;
+      if (bodySchema) {
+        let rawBody;
+        try {
+          rawBody = await request.json();
+          requestBodyString = JSON.stringify(rawBody);
+        } catch (e) {
+          const errorResp = _server.NextResponse.json(
+            { success: false, error: "Invalid JSON body" },
+            { status: 400 }
+          );
+          log(400, JSON.stringify({ success: false, error: "Invalid JSON body" }), errorResp);
+          return errorResp;
+        }
+        const parsed = bodySchema.safeParse(rawBody);
+        if (!parsed.success) {
+          const message = formatValidationError(parsed.error);
+          const errorBody = {
+            success: false,
+            error: "Validation failed",
+            message,
+            details: parsed.error.flatten()
+          };
+          const errorResp = _server.NextResponse.json(errorBody, { status: 400 });
+          log(400, JSON.stringify(errorBody), errorResp);
+          return errorResp;
+        }
+        body = parsed.data;
+      }
+      if (querySchema) {
+        const searchParams = Object.fromEntries(request.nextUrl.searchParams);
+        const parsed = querySchema.safeParse(searchParams);
+        if (!parsed.success) {
+          const message = formatValidationError(parsed.error);
+          const errorBody = {
+            success: false,
+            error: "Query validation failed",
+            message,
+            details: parsed.error.flatten()
+          };
+          const errorResp = _server.NextResponse.json(errorBody, { status: 400 });
+          log(400, JSON.stringify(errorBody), errorResp);
+          return errorResp;
+        }
+        query = parsed.data;
+      }
+      let response;
+      try {
+        response = await fn({ body, query, request, telemetry: ctx });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        const status = error instanceof HttpError ? error.status : 500;
+        const errorBody = { success: false, error: message };
+        const errorResp = _server.NextResponse.json(errorBody, { status });
+        log(status, JSON.stringify(errorBody), errorResp);
+        return errorResp;
+      }
+      if (response && typeof response === "object" && "success" in response && !response.success) {
+        const errorResp = _server.NextResponse.json(response, { status: 500 });
+        log(500, JSON.stringify(response), errorResp);
+        return errorResp;
+      }
+      const successResp = _server.NextResponse.json(response);
+      let responseBodyString = null;
+      try {
+        responseBodyString = JSON.stringify(response);
+      } catch (e2) {
+      }
+      log(200, responseBodyString, successResp);
+      return successResp;
+    };
+    if (accepts.length === 0) {
+      return coreHandler;
+    }
+    const X402_BYPASS = process.env.X402_BYPASS === "true";
+    if (X402_BYPASS) {
+      return coreHandler;
+    }
+    const X402_PAYEE_ADDRESS = process.env.X402_PAYEE_ADDRESS;
+    if (!X402_PAYEE_ADDRESS) {
+      throw new Error("X402_PAYEE_ADDRESS environment variable is required when using .price()");
+    }
+    const routeConfig = {
+      description,
+      accepts: accepts.map(({ amount, network, asset }) => ({
+        scheme: "exact",
+        network,
+        price: amount,
+        payTo: X402_PAYEE_ADDRESS,
+        ...asset && { extra: { asset } }
+      })),
+      extensions: buildDiscoveryExtensions(bodySchema, querySchema, outputSchema, outputExample)
+    };
+    if (!this.options.x402Server) {
+      throw new Error(
+        "x402Server is required when using .price(). Pass it to createRouteBuilder({ x402Server })."
+      );
+    }
+    return _next.withX402.call(void 0, coreHandler, routeConfig, this.options.x402Server);
+  }
+};
+function buildDiscoveryExtensions(bodySchema, querySchema, outputSchema, outputExample) {
+  const inputJsonSchema = bodySchema ? _zod.z.toJSONSchema(bodySchema, { target: "draft-2020-12" }) : querySchema ? _zod.z.toJSONSchema(querySchema, { target: "draft-2020-12" }) : void 0;
+  const outputJsonSchema = outputSchema ? _zod.z.toJSONSchema(outputSchema, { target: "draft-2020-12" }) : void 0;
+  if (!inputJsonSchema) return void 0;
+  const config = {
+    bodyType: bodySchema ? "json" : void 0,
+    inputSchema: inputJsonSchema,
+    output: outputJsonSchema ? { schema: outputJsonSchema, example: _nullishCoalesce(outputExample, () => ( {})) } : void 0
+  };
+  return { ..._bazaar.declareDiscoveryExtension.call(void 0, config) };
+}
+function createRouteBuilder(options) {
+  return new RouteBuilder(void 0, options);
+}
+
+
+
+exports.HttpError = HttpError; exports.createRouteBuilder = createRouteBuilder;
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/samragsdale/Documents/Code/merit-systems/agentcash-telemetry/dist/builder.js","../src/route-builder.ts"],"names":[],"mappings":"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","file":"/Users/samragsdale/Documents/Code/merit-systems/agentcash-telemetry/dist/builder.js","sourcesContent":[null,"/**\n * Convenience route builder that composes telemetry + validation + x402 wrapping.\n * This is optional — servers can use withTelemetry directly.\n *\n * Import from '@agentcash/telemetry/builder'.\n * Requires peer deps: @x402/next, zod (^4), @x402/extensions\n */\n\nimport { type NextRequest, NextResponse } from 'next/server';\nimport { withX402 } from '@x402/next';\nimport { z, type ZodType } from 'zod';\nimport { declareDiscoveryExtension } from '@x402/extensions/bazaar';\nimport type { TelemetryContext } from './types';\nimport { extractRequestMeta, buildTelemetryContext, recordInvocation } from './telemetry-core';\n\nexport class HttpError extends Error {\n  constructor(\n    message: string,\n    public status: number,\n  ) {\n    super(message);\n    this.name = 'HttpError';\n  }\n}\n\ntype AcceptsOption = {\n  amount: string;\n  network: string;\n  asset?: string;\n};\n\ntype BuilderConfig<TBody = unknown, TQuery = unknown, TOutput = unknown> = {\n  accepts: AcceptsOption[];\n  bodySchema?: ZodType<TBody>;\n  querySchema?: ZodType<TQuery>;\n  outputSchema?: ZodType<TOutput>;\n  outputExample?: TOutput;\n  description?: string;\n};\n\ntype HandlerContext<TBody, TQuery> = {\n  body: TBody;\n  query: TQuery;\n  request: NextRequest;\n  telemetry: TelemetryContext;\n};\n\ntype HandlerFn<TBody, TQuery, TResponse> = (\n  ctx: HandlerContext<TBody, TQuery>,\n) => Promise<TResponse>;\n\nfunction formatValidationError(error: import('zod').ZodError): string {\n  const issues = error.issues;\n  if (issues.length === 0) return 'Validation failed';\n\n  if (issues.length === 1) {\n    const issue = issues[0];\n    const path = issue.path.join('.');\n    const field = path || 'request';\n    if (issue.message) return `${field}: ${issue.message}`;\n    return `${field}: Invalid value`;\n  }\n\n  const errors = issues.map((issue) => {\n    const path = issue.path.join('.');\n    const field = path || 'request';\n    return issue.message ? `${field}: ${issue.message}` : `${field}: Invalid`;\n  });\n\n  return `Validation failed: ${errors.join('; ')}`;\n}\n\nexport interface RouteBuilderOptions {\n  /** The x402 resource server instance (from @x402/core/server). Required when using .price(). */\n  x402Server?: unknown;\n}\n\nclass RouteBuilder<TBody = unknown, TQuery = unknown, TOutput = unknown> {\n  private config: BuilderConfig<TBody, TQuery, TOutput>;\n  private options: RouteBuilderOptions;\n\n  constructor(\n    config?: Partial<BuilderConfig<TBody, TQuery, TOutput>>,\n    options?: RouteBuilderOptions,\n  ) {\n    this.config = { accepts: [], ...config };\n    this.options = options ?? {};\n  }\n\n  price(amount: string, network: string, asset?: string) {\n    return new RouteBuilder<TBody, TQuery, TOutput>(\n      { ...this.config, accepts: [{ amount, network, asset }] },\n      this.options,\n    );\n  }\n\n  accepts(options: AcceptsOption[]) {\n    return new RouteBuilder<TBody, TQuery, TOutput>(\n      { ...this.config, accepts: options },\n      this.options,\n    );\n  }\n\n  body<T>(schema: ZodType<T>) {\n    return new RouteBuilder<T, TQuery, TOutput>(\n      { ...this.config, bodySchema: schema as ZodType<unknown> } as BuilderConfig<\n        T,\n        TQuery,\n        TOutput\n      >,\n      this.options,\n    );\n  }\n\n  query<T>(schema: ZodType<T>) {\n    return new RouteBuilder<TBody, T, TOutput>(\n      { ...this.config, querySchema: schema as ZodType<unknown> } as BuilderConfig<\n        TBody,\n        T,\n        TOutput\n      >,\n      this.options,\n    );\n  }\n\n  output<T>(schema: ZodType<T>, example?: T) {\n    return new RouteBuilder<TBody, TQuery, T>(\n      {\n        ...this.config,\n        outputSchema: schema as ZodType<unknown>,\n        outputExample: example,\n      } as BuilderConfig<TBody, TQuery, T>,\n      this.options,\n    );\n  }\n\n  description(text: string) {\n    return new RouteBuilder<TBody, TQuery, TOutput>(\n      { ...this.config, description: text },\n      this.options,\n    );\n  }\n\n  handler<TResponse>(fn: HandlerFn<TBody, TQuery, TResponse>) {\n    const { accepts, bodySchema, querySchema, outputSchema, outputExample, description } =\n      this.config;\n\n    const coreHandler = async (request: NextRequest): Promise<NextResponse> => {\n      const meta = extractRequestMeta(request);\n      const ctx = buildTelemetryContext(meta);\n\n      const log = (status: number, responseBody: string | null, resp: NextResponse) => {\n        recordInvocation(meta, requestBodyString, {\n          status,\n          body: responseBody,\n          headers: JSON.stringify(Object.fromEntries(resp.headers.entries())),\n          contentType: resp.headers.get('content-type') ?? null,\n        });\n      };\n\n      // Parse and validate body\n      let body: TBody = undefined as TBody;\n      let query: TQuery = undefined as TQuery;\n      let requestBodyString: string | null = null;\n\n      if (bodySchema) {\n        let rawBody: unknown;\n        try {\n          rawBody = await request.json();\n          requestBodyString = JSON.stringify(rawBody);\n        } catch {\n          const errorResp = NextResponse.json(\n            { success: false, error: 'Invalid JSON body' },\n            { status: 400 },\n          );\n          log(400, JSON.stringify({ success: false, error: 'Invalid JSON body' }), errorResp);\n          return errorResp;\n        }\n\n        const parsed = bodySchema.safeParse(rawBody);\n        if (!parsed.success) {\n          const message = formatValidationError(parsed.error);\n          const errorBody = {\n            success: false,\n            error: 'Validation failed',\n            message,\n            details: parsed.error.flatten(),\n          };\n          const errorResp = NextResponse.json(errorBody, { status: 400 });\n          log(400, JSON.stringify(errorBody), errorResp);\n          return errorResp;\n        }\n        body = parsed.data;\n      }\n\n      // Parse and validate query\n      if (querySchema) {\n        const searchParams = Object.fromEntries(request.nextUrl.searchParams);\n        const parsed = querySchema.safeParse(searchParams);\n        if (!parsed.success) {\n          const message = formatValidationError(parsed.error);\n          const errorBody = {\n            success: false,\n            error: 'Query validation failed',\n            message,\n            details: parsed.error.flatten(),\n          };\n          const errorResp = NextResponse.json(errorBody, { status: 400 });\n          log(400, JSON.stringify(errorBody), errorResp);\n          return errorResp;\n        }\n        query = parsed.data;\n      }\n\n      // Execute user handler\n      let response: TResponse;\n      try {\n        response = await fn({ body, query, request, telemetry: ctx });\n      } catch (error: unknown) {\n        const message = error instanceof Error ? error.message : 'Unknown error';\n        const status = error instanceof HttpError ? error.status : 500;\n        const errorBody = { success: false, error: message };\n        const errorResp = NextResponse.json(errorBody, { status });\n        log(status, JSON.stringify(errorBody), errorResp);\n        return errorResp;\n      }\n\n      // Detect { success: false } to prevent x402 settlement\n      if (\n        response &&\n        typeof response === 'object' &&\n        'success' in response &&\n        !(response as { success: boolean }).success\n      ) {\n        const errorResp = NextResponse.json(response, { status: 500 });\n        log(500, JSON.stringify(response), errorResp);\n        return errorResp;\n      }\n\n      // Success\n      const successResp = NextResponse.json(response);\n      let responseBodyString: string | null = null;\n      try {\n        responseBodyString = JSON.stringify(response);\n      } catch {\n        // Not serializable — that's fine\n      }\n      log(200, responseBodyString, successResp);\n      return successResp;\n    };\n\n    // If no pricing, return the core handler directly (no x402 wrapping)\n    if (accepts.length === 0) {\n      return coreHandler;\n    }\n\n    // Wrap with x402\n    const X402_BYPASS = process.env.X402_BYPASS === 'true';\n    if (X402_BYPASS) {\n      return coreHandler;\n    }\n\n    const X402_PAYEE_ADDRESS = process.env.X402_PAYEE_ADDRESS;\n    if (!X402_PAYEE_ADDRESS) {\n      throw new Error('X402_PAYEE_ADDRESS environment variable is required when using .price()');\n    }\n\n    const routeConfig = {\n      description,\n      accepts: accepts.map(({ amount, network, asset }) => ({\n        scheme: 'exact' as const,\n        network: network as `${string}:${string}`,\n        price: amount,\n        payTo: X402_PAYEE_ADDRESS,\n        ...(asset && { extra: { asset } }),\n      })),\n      extensions: buildDiscoveryExtensions(bodySchema, querySchema, outputSchema, outputExample),\n    };\n\n    if (!this.options.x402Server) {\n      throw new Error(\n        'x402Server is required when using .price(). Pass it to createRouteBuilder({ x402Server }).',\n      );\n    }\n\n    return withX402(coreHandler, routeConfig, this.options.x402Server as never);\n  }\n}\n\nfunction buildDiscoveryExtensions(\n  bodySchema?: ZodType<unknown>,\n  querySchema?: ZodType<unknown>,\n  outputSchema?: ZodType<unknown>,\n  outputExample?: unknown,\n): Record<string, unknown> | undefined {\n  const inputJsonSchema = bodySchema\n    ? z.toJSONSchema(bodySchema, { target: 'draft-2020-12' })\n    : querySchema\n      ? z.toJSONSchema(querySchema, { target: 'draft-2020-12' })\n      : undefined;\n\n  const outputJsonSchema = outputSchema\n    ? z.toJSONSchema(outputSchema, { target: 'draft-2020-12' })\n    : undefined;\n\n  if (!inputJsonSchema) return undefined;\n\n  const config = {\n    bodyType: bodySchema ? 'json' : undefined,\n    inputSchema: inputJsonSchema,\n    output: outputJsonSchema\n      ? { schema: outputJsonSchema, example: outputExample ?? {} }\n      : undefined,\n  };\n\n  return { ...declareDiscoveryExtension(config as never) };\n}\n\n/**\n * Create a new route builder instance.\n */\nexport function createRouteBuilder(options?: RouteBuilderOptions) {\n  return new RouteBuilder(undefined, options);\n}\n"]}