import { ClientTraceEvent } from '@voltro/client';
import { reportClientError } from '@voltro/client';

/** Report a client error (route render/loader failure OR a manual capture) to
 *  Sentry, tagged with its source + route + React component stack. Pure given
 *  a `SentryBrowserLike` — unit-testable with a fake. */
export declare const captureClientError: (sentry: SentryBrowserLike, event: {
    readonly error: unknown;
    readonly source: string;
    readonly componentStack?: string;
    readonly pathname?: string;
    readonly context?: Record<string, unknown>;
}) => void;

/** Tear down the trace + error bridges (tests / hot-reload). */
export declare const closeSentryBrowser: () => void;

/** Initialise browser-side Sentry + wire the rpc trace bridge. Idempotent-ish:
 *  a second call re-subscribes the bridge (disposing the first). No-op on the
 *  server (SSR) and without a DSN. */
export declare const initSentryBrowser: (options?: SentryBrowserOptions) => Promise<void>;

/** Emit a browser-side Sentry span into the SAME trace as the server
 *  transaction the call will produce. */
export declare const recordClientTraceSpan: (sentry: SentryBrowserLike, event: ClientTraceEvent) => void;

export { reportClientError }

export declare interface SentryBrowserLike {
    continueTrace<T>(context: {
        sentryTrace: string;
        baggage?: string;
    }, callback: () => T): T;
    startInactiveSpan(options: {
        name: string;
        op?: string;
        attributes?: Record<string, unknown>;
    }): SentrySpanLike;
    withScope(callback: (scope: SentryBrowserScopeLike) => void): unknown;
    captureException(exception: unknown): unknown;
}

export declare interface SentryBrowserOptions {
    /** Sentry DSN (public — safe in the browser bundle). Without it → no-op. */
    readonly dsn?: string;
    /** `environment` tag. */
    readonly environment?: string;
    /** Release identifier (must match the server's `release` for unified
     *  release health + source maps). */
    readonly release?: string;
    /** Performance-trace sample rate (0..1). Default 1.0. */
    readonly tracesSampleRate?: number;
    /** Instrument page loads + client navigations via `browserTracingIntegration`.
     *  Default true. */
    readonly browserTracing?: boolean;
}

declare interface SentryBrowserScopeLike {
    setTag(key: string, value: string): unknown;
    setContext(key: string, context: Record<string, unknown> | null): unknown;
}

/** Minimal structural slice of `@sentry/react` we use — keeps this testable
 *  with a fake; the real module satisfies it structurally. */
declare interface SentrySpanLike {
    end(): void;
}

/** Build the `sentry-trace` header for a client trace event (sampled=1 — the
 *  framework records always-on; Sentry's client applies its own sample rate). */
export declare const sentryTraceHeader: (event: ClientTraceEvent) => string;

export { }