import { Span, Tracer } from "@opentelemetry/api";

//#region src/utils/tracer-factory.d.ts

/**
 * Unwraps nested error `.cause` chains to find the root cause error.
 * Node.js `fetch()` wraps undici errors (e.g. HeadersTimeoutError) into
 * a generic `TypeError: fetch failed` with the real error in `.cause`.
 * This utility traverses the cause chain to surface the original error.
 */
declare function unwrapError(error: unknown): Error;
/**
 * Helper function to handle span errors consistently
 * Records the exception, sets error status, and optionally logs.
 * Automatically unwraps `.cause` chains so spans show root cause errors
 * instead of generic wrappers like "fetch failed".
 */
declare function setSpanWithError(span: Span, error: Error, logger?: {
  error: (obj: any, msg?: string) => void;
}, logMessage?: string): void;
/**
 * Get a tracer instance for the specified service
 * Returns a no-op tracer if OpenTelemetry is not available
 */
declare function getTracer(serviceName: string, serviceVersion?: string): Tracer;
/**
 * Force-flush all pending trace spans to the configured exporter.
 *
 * Uses the global TracerProvider registered by the OpenTelemetry SDK.
 * This is safe to call from any package — it accesses the same provider
 * that was set up in the host application's instrumentation.
 *
 * Use this in fire-and-forget handlers (e.g. Slack webhooks) where the
 * HTTP response is sent before background work completes, so the
 * per-request flush middleware runs too early to capture those spans.
 */
declare function flushTraces(): Promise<void>;
//#endregion
export { flushTraces, getTracer, setSpanWithError, unwrapError };