import { type Span } from '@opentelemetry/api';
/**
 * Attribute key under which the OTel server span is stashed on the
 * per-request `RequestContext.items` map.
 *
 * Downstream middleware/handlers can read this with
 * `ctx.items.get(OTEL_SPAN_ITEM_KEY)` to attach custom attributes
 * or events to the active server span.
 */
export declare const OTEL_SPAN_ITEM_KEY = "otel.span";
/**
 * Configuration for {@link tracingMiddleware}.
 */
export interface TracingMiddlewareOptions {
    /**
     * Tracer name used when resolving the OTel tracer.
     *
     * @default '@cleverbrush/otel'
     */
    tracerName?: string;
    /** Tracer version. */
    tracerVersion?: string;
    /**
     * Paths to exclude from tracing entirely (no span created).
     *
     * Accepts plain strings or objects with a `path` property
     * (e.g. an `EndpointBuilder`). Useful for `/health` and other
     * high-frequency, low-value endpoints.
     */
    excludePaths?: (string | {
        readonly path: string;
    })[];
    /**
     * Hook for adding custom attributes to the server span just before
     * the inner pipeline runs. Errors thrown here are swallowed.
     */
    enrichSpan?: (span: Span, ctx: any) => void;
    /**
     * Whether to record the URL query string as `url.query`.
     *
     * Disabled by default because query strings frequently contain PII
     * (search terms, tokens). Enable explicitly only when you have
     * verified your URLs are safe to record.
     *
     * @default false
     */
    recordQuery?: boolean;
    /**
     * Name of the response header that carries the W3C trace ID for the
     * current request span.
     *
     * Expose this so API consumers can include it in bug reports and you
     * can look up the exact trace in SigNoz / Jaeger / etc.
     *
     * Set to `false` to disable the header entirely.
     *
     * @default 'X-Trace-Id'
     */
    responseTraceHeader?: string | false;
}
/**
 * Creates a `@cleverbrush/server` middleware that opens an OpenTelemetry
 * `SERVER` span for every incoming request.
 *
 * Should be registered as the **first** middleware so that the span
 * wraps CORS, auth, request logging, and the handler — capturing the
 * full request lifetime.
 *
 * Behavior:
 * - Extracts inbound trace context from request headers
 *   (W3C `traceparent`, `baggage`).
 * - Names the span `${operationId}` if available, otherwise
 *   `${method} ${http.route}`, otherwise `${method} ${url.path}`.
 * - Sets HTTP semantic-convention attributes
 *   (`http.request.method`, `url.path`, `url.scheme`,
 *   `server.address`, `user_agent.original`, `http.route`).
 * - Records `http.response.status_code` after `next()` completes.
 * - Marks the span `ERROR` and records the exception on uncaught errors.
 * - Stashes the span at `ctx.items.get(OTEL_SPAN_ITEM_KEY)` for
 *   downstream code to enrich.
 *
 * @param options - tracing configuration
 * @returns a `Middleware` compatible with `@cleverbrush/server`
 *
 * @example
 * ```ts
 * import { tracingMiddleware } from '@cleverbrush/otel';
 *
 * createServer()
 *     .use(tracingMiddleware({ excludePaths: ['/health'] }))
 *     .use(corsMiddleware)
 *     .use(authMiddleware)
 *     .listen(3000);
 * ```
 */
export declare function tracingMiddleware(options?: TracingMiddlewareOptions): (ctx: any, next: () => Promise<void>) => Promise<void>;