import * as _opentelemetry_api from '@opentelemetry/api';
import { Span, SpanOptions } from '@opentelemetry/api';
import * as moost from 'moost';
import { Mate, TMoostMetadata, TMateParamMeta, ContextInjector, TContextInjectorHook } from 'moost';
import { EventContext } from '@wooksjs/event-core';
import { BatchSpanProcessor, ReadableSpan, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import * as http from 'http';
import { ServerResponse } from 'http';

/** Event context key storing the root OpenTelemetry span. */
declare const otelSpanKey: moost.Key<Span | undefined>;
/** Event context key storing the resolved route path for span naming. */
declare const otelRouteKey: moost.Key<string | undefined>;
/** Event context key storing the event start time (epoch ms) for duration metrics. */
declare const otelStartTimeKey: moost.Key<number | undefined>;
/** Event context key storing custom span attributes set via `useOtelContext().customSpanAttr()`. */
declare const customSpanAttrsKey: moost.Key<Record<string, string | number>>;
/** Event context key storing custom metric attributes set via `useOtelContext().customMetricAttr()`. */
declare const customMetricAttrsKey: moost.Key<Record<string, string | number>>;
/**
 * Provides OpenTelemetry tracing utilities scoped to the current event.
 * Must be called within an active event handler context.
 *
 * @returns Tracing utilities including span access, propagation headers, and custom attributes.
 */
declare function useOtelContext(ctx?: EventContext): {
    trace: _opentelemetry_api.TraceAPI;
    getSpan: () => Span | undefined;
    getSpanContext: () => _opentelemetry_api.SpanContext | undefined;
    getPropagationHeaders: () => {
        traceparent: string;
        tracestate: _opentelemetry_api.TraceState | undefined;
    } | {
        traceparent?: undefined;
        tracestate?: undefined;
    };
    registerSpan: (span: Span) => void;
    pushSpan: (span: Span) => void;
    customSpanAttr: (name: string, value: string | number) => void;
    customMetricAttr: (name: string, value: string | number) => void;
};
/** Returns the OpenTelemetry `trace` API for creating tracers and spans. */
declare function useTrace(): _opentelemetry_api.TraceAPI;
/** Returns the root span for the current event, or `undefined` if no span is active. */
declare function useSpan(): Span | undefined;
/**
 * Returns W3C trace-context propagation data for the current event.
 * Use the returned `headers` (traceparent, tracestate) in outgoing HTTP requests
 * to propagate the trace to downstream services.
 */
declare function useOtelPropagation(): {
    headers: {
        traceparent: string;
        tracestate: _opentelemetry_api.TraceState | undefined;
    } | {
        traceparent?: undefined;
        tracestate?: undefined;
    };
    traceId?: string | undefined;
    spanId?: string | undefined;
    isRemote?: boolean;
    traceFlags?: number | undefined;
    traceState?: _opentelemetry_api.TraceState;
};

/**
 * Enables OpenTelemetry integration for Moost by replacing the default
 * context injector with a span-aware `SpanInjector`.
 * Call this before creating or starting your Moost application.
 */
declare function enableOtelForMoost(): void;

/**
 * Annotate controller and/or handler to filter
 * out the corresponding spans from transporting
 *
 * Requires use of MoostBatchSpanProcessor or MoostSimpleSpanProcessor
 */
declare const OtelIgnoreSpan: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
/**
 * Annotate controller and/or handler to suppress metrics
 */
declare const OtelIgnoreMeter: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;

/** OpenTelemetry metadata fields attached to classes and methods by OTEL decorators. */
interface TOtelMate {
    otelIgnoreSpan: boolean;
    otelIgnoreMeter: boolean;
}
/** Returns the shared `Mate` instance extended with OpenTelemetry metadata fields. */
declare function getOtelMate(): Mate<TMoostMetadata & TOtelMate & {
    params: (TOtelMate & TMateParamMeta)[];
}, TMoostMetadata & TOtelMate & {
    params: (TOtelMate & TMateParamMeta)[];
}>;

/**
 * Batch span processor that filters out spans marked with `@OtelIgnoreSpan()`.
 * Drop-in replacement for `BatchSpanProcessor` from `@opentelemetry/sdk-trace-base`.
 */
declare class MoostBatchSpanProcessor extends BatchSpanProcessor {
    onEnd(span: ReadableSpan): void;
}

/**
 * Simple span processor that filters out spans marked with `@OtelIgnoreSpan()`.
 * Drop-in replacement for `SimpleSpanProcessor` from `@opentelemetry/sdk-trace-base`.
 */
declare class MoostSimpleSpanProcessor extends SimpleSpanProcessor {
    onEnd(span: ReadableSpan): void;
}

/** Returns `true` if the span has the `moost.ignore` attribute set by `@OtelIgnoreSpan()`. */
declare function shouldSpanBeIgnored(span: ReadableSpan): boolean;

type TAttributes = Record<string, string | number | boolean>;
/** Context injector that wraps Moost lifecycle hooks with OpenTelemetry spans and records metrics. */
declare class SpanInjector extends ContextInjector<TContextInjectorHook> {
    metrics: {
        moostEventDuration: _opentelemetry_api.Histogram;
    };
    with<T>(name: TContextInjectorHook, attributes: TAttributes, cb: () => T): T;
    with<T>(name: TContextInjectorHook, cb: () => T): T;
    protected patchRsponse(): void;
    protected startEvent<T>(eventType: string, cb: () => T): T;
    getEventType(): string | undefined;
    getIgnoreSpan(): boolean | undefined;
    getControllerHandlerMeta(): {
        ignoreMeter: boolean | undefined;
        ignoreSpan: boolean | undefined;
        attrs: {
            'moost.controller': string | undefined;
            'moost.handler': string | undefined;
            'moost.handler_description': string | undefined;
            'moost.handler_label': string | undefined;
            'moost.handler_id': string | undefined;
            'moost.ignore': boolean | undefined;
            'moost.route': string;
            'moost.event_type': string | undefined;
        };
    };
    hook(method: string, name: 'Handler:not_found' | 'Handler:routed' | 'Controller:registered', route?: string): void;
    withSpan<T>(span: Span, cb: () => T, opts: {
        withMetrics: boolean;
        endSpan: boolean;
    }): T;
    startEventMetrics(a: Record<string, string | number | boolean | undefined>, route?: string): void;
    endEventMetrics(a: Record<string, string | number | boolean | undefined>, error?: Error): void;
    getRequest(): http.IncomingMessage | undefined;
    getResponse(): (ServerResponse<http.IncomingMessage> & {
        _statusCode?: number;
        _contentLength?: number;
    }) | undefined;
}

/** Callback invoked after span execution for enrichment. When provided, you must call `span.end()` yourself. */
type TPostSpanProcessFn<T> = (span: Span, exception: Error | undefined, result: Awaited<T> | undefined) => void;
/** Input for creating a new span with `withSpan()`. */
interface TSpanInput {
    name: string;
    options?: SpanOptions;
}
/**
 * Starts or continues a span, executes the callback within the span's context,
 * and handles span completion and error recording. Supports both synchronous and asynchronous callbacks.
 * An optional post-processing callback can be used to enrich the span before it ends.
 *
 * @template T
 * @param {TSpanInput | Span} span - The span input containing name and options, or an existing span.
 * @param {() => T} cb - The callback function to execute within the span's context.
 * @param {TPostSpanProcessFn<T>=} postProcess - An optional post-processing callback to enrich the span before it ends. **CAUTION: When used, you must end the span yourself `span.end()`.**
 * @returns {T} The result of the callback function.
 * @throws {Error} Will throw an error if the callback function throws.
 */
declare function withSpan<T>(span: TSpanInput | Span, cb: () => T, postProcess?: TPostSpanProcessFn<T>): T;

export { MoostBatchSpanProcessor, MoostSimpleSpanProcessor, OtelIgnoreMeter, OtelIgnoreSpan, SpanInjector, customMetricAttrsKey, customSpanAttrsKey, enableOtelForMoost, getOtelMate, otelRouteKey, otelSpanKey, otelStartTimeKey, shouldSpanBeIgnored, useOtelContext, useOtelPropagation, useSpan, useTrace, withSpan };
export type { TOtelMate, TPostSpanProcessFn, TSpanInput };