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>;

/**
 * Is this client-side event a DECLARED failure?
 *
 * Two conditions, and both are needed. The source must be an `rpc.*` one — a
 * route render throw or a manual `reportClientError` is nobody's declared
 * outcome. And the value must carry a `_tag`: the framework's typed errors are
 * `Schema.TaggedError` subclasses, so a decoded one has one, while a transport
 * failure, an aborted socket or a forwarded defect does not.
 *
 * The rule is deliberately narrow. Anything it cannot positively identify as
 * declared is reported, because the cost of the two mistakes is not symmetric:
 * a noisy issue is read and dismissed, a missing one is never read.
 */
export declare const isDeclaredRpcFailure: (event: {
    source: string;
    error: unknown;
}) => boolean;

/** Add an rpc marker to the active page/navigation transaction and link it to
 *  the Effect trace continued by the server. With no active browser parent,
 *  `onlyIfParent` deliberately produces no recorded root transaction. */
export declare const recordClientTraceSpan: (sentry: SentryBrowserLike, event: ClientTraceEvent) => void;

export { reportClientError }

export declare interface SentryBrowserLike {
    startInactiveSpan(options: {
        name: string;
        op?: string;
        onlyIfParent?: boolean;
        attributes?: Record<string, unknown>;
        links?: ReadonlyArray<{
            context: {
                traceId: string;
                spanId: string;
                traceFlags: number;
            };
            attributes?: Record<string, string | number | boolean>;
        }>;
    }): 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;
    /** Record rpc markers under the active page/navigation transaction and link
     *  them to their server traces. Defaults to `browserTracing`; set `false` to
     *  disable only this bridge while keeping browser error reporting. Set
     *  `true` with `browserTracing:false` only when the app creates its own
     *  active Sentry transactions. */
    readonly rpcSpans?: boolean;
    /**
     * Whether a DECLARED failure that came back from an rpc call reaches Sentry.
     * **Default `false`**, matching `sentryPlugin({ captureFailures })`.
     *
     * Both halves need it or neither works. The api stops reporting
     * `AccessDeniedError` and the browser keeps filing the same rejection,
     * because a rejected call is an rpc error on this side too — the option would
     * be half-wired, and the issue list would look unchanged.
     *
     * Route render failures and explicit `reportClientError` calls are NEVER
     * filtered by this: nobody declared them, which is the whole distinction.
     */
    readonly captureFailures?: boolean | 'infrastructure' | ((error: unknown) => 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;
}

export { }