/** Console methods we can forward, in increasing severity. */
type ConsoleLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';

/**
 * Authenticated end-user identity passed to {@link setUser}. `id` is required; the
 * label/role are optional. Numbers are accepted for `id` and stringified.
 */
interface ObservUser {
    /** Stable application user id → `enduser.id`. */
    id: string | number;
    /** Optional role/permission tag → `enduser.role`. */
    role?: string;
    /** Optional display name → `enduser.name` (avoid storing raw PII if sensitive). */
    name?: string;
}
/** Attach the authenticated user to all subsequent telemetry. */
declare function setUser(user: ObservUser): void;
/** Clear the authenticated identity (call on sign-out). The pseudo id persists. */
declare function clearUser(): void;

/**
 * PII masking / privacy controls for the heavy rrweb replay flux
 * (Epic 4 — Confidentialité, story 4.1).
 *
 * SAFE-BY-DEFAULT: omitting `privacy` (or any field) masks all input values in
 * the replay. Architecture D7 / PRD Open Q5 require masking before any real
 * data. Three conventional CSS classes let a host page mark sensitive nodes
 * declaratively; only override a class name if it collides with the host's.
 */
interface PrivacyOptions {
    /**
     * Mask the value of every `<input>`/`<textarea>`/`<select>` in the replay
     * (rrweb `maskAllInputs`). Default: `true`. Set `false` ONLY on a surface
     * known to be free of sensitive input.
     */
    maskAllInputs?: boolean;
    /**
     * Also mask ALL visible text content in the replay, not just inputs (rrweb
     * `maskTextSelector: '*'`). Default: `false` — full-text masking strongly
     * degrades replay usefulness, so it is opt-in per surface.
     */
    maskAllText?: boolean;
    /**
     * CSS class marking elements whose TEXT must be masked in the replay
     * (rrweb `maskTextClass`). Default: `observ-mask`.
     */
    maskTextClass?: string;
    /**
     * CSS class marking elements to DROP entirely from the replay — recorded as
     * an empty placeholder (rrweb `blockClass`). Default: `observ-block`.
     */
    blockClass?: string;
    /**
     * CSS class marking inputs whose user input events are IGNORED — the element
     * is still recorded but its value changes are not (rrweb `ignoreClass`).
     * Default: `observ-ignore`.
     */
    ignoreClass?: string;
}

/**
 * Public option bag for {@link observ.init}.
 *
 * Scaffold story (1.1): only `endpoint`, `key` and `propagateTraceHeaderCorsUrls`
 * are part of the committed public surface. Fields consumed by later stories
 * (session lifecycle, rrweb capture, sampling…) are intentionally NOT declared
 * yet — each story that needs one adds it, so the surface stays honest.
 */
interface ObservInitOptions {
    /** Base URL of the Observ backend receiving telemetry, e.g. `https://obs.example.com`. */
    endpoint: string;
    /** API key authenticating the browser against the Observ ingestion endpoints. */
    key: string;
    /**
     * Origins for which OTel may propagate the W3C `traceparent` header on
     * cross-origin fetch/XHR. Required for `session.id ⇄ trace_id` correlation
     * when the backend is not same-origin (see architecture D6 / PRD NFR-5).
     * Wired up in story 1.3; accepted (and ignored) here.
     */
    propagateTraceHeaderCorsUrls?: (string | RegExp)[];
    /**
     * Disable rrweb session-replay capture (story 2.2). OTel RUM tracing stays on.
     * Use for sensitive surfaces where even masked replay is unwanted; otherwise
     * prefer `privacy` masking (story 4.1), which is on by default. Default:
     * replay enabled.
     */
    disableReplay?: boolean;
    /**
     * PII masking controls for the heavy replay flux (story 4.1). Safe-by-default:
     * omit to mask all input values. See {@link PrivacyOptions}.
     */
    privacy?: PrivacyOptions;
    /**
     * `service.name` stamped on every signal's resource. Without it spans/logs/
     * metrics land under `unknown_service`. Set it per app (e.g. `cotevins-front`).
     */
    serviceName?: string;
    /** `service.version` resource attribute (e.g. the app build / release). */
    serviceVersion?: string;
    /** `deployment.environment.name` resource attribute (e.g. `prod`, `dev`). */
    environment?: string;
    /**
     * Disable the metrics pipeline (Core Web Vitals histograms + nav/error
     * counters over OTLP/HTTP to `{endpoint}/v1/metrics`). Default: metrics ON.
     */
    disableMetrics?: boolean;
    /**
     * Propagate `session.id` to backends via the W3C `baggage` header on
     * fetch/XHR, so server spans can stamp the session identity. The allowlist is
     * {@link propagateTraceHeaderCorsUrls} (same backends that receive
     * `traceparent`). Default: off. Same-origin requests are always eligible.
     */
    propagateBaggage?: boolean;
    /**
     * Head-based trace sampling ratio in `[0, 1)` (e.g. `0.2` keeps 20% of root
     * traces) via a `ParentBasedSampler`. Omit / `>= 1` / invalid ⇒ sample all
     * (AlwaysOn). Use under heavy traffic to bound RUM volume.
     */
    sampleRate?: number;
    /**
     * Inactivity window (ms) after which the `session.id` rotates. A fresh session
     * is chained to the prior one via `session.previous_id`. Default: 30 min.
     */
    sessionInactivityMs?: number;
    /**
     * Hard cap (ms) on a single session's total duration, regardless of activity —
     * a session older than this rotates even under continuous use. Default: 4 h.
     */
    sessionMaxDurationMs?: number;
    /**
     * Share one session across the visitor's tabs by backing it with `localStorage`
     * + the `storage` event, instead of the default per-tab `sessionStorage`
     * (where two tabs are deliberately two visits). Opt-in: the historical per-tab
     * model is preserved unless this is `true`. Default: `false`.
     */
    crossTabSessions?: boolean;
    /**
     * Disable the pseudonymous, persistent `enduser.pseudo.id` (a random id kept in
     * `localStorage` that ties a visitor's sessions together without authenticated
     * PII). Default: enabled. The authenticated `enduser.id` (via {@link ObservSdk.setUser})
     * is unaffected by this flag.
     */
    disablePseudoUser?: boolean;
    /**
     * Mirror `console.*` calls to the OTLP logs pipeline (each record carries
     * `session.id` + end-user identity, severity-mapped). The original console is
     * always still called. `true` forwards `debug`/`log`/`info`/`warn`/`error`; an
     * array restricts to specific levels (e.g. `['warn', 'error']`). Opt-in
     * (default off) — console output can be noisy and may contain PII.
     */
    forwardConsole?: boolean | ConsoleLevel[];
    /**
     * Disable rich `app.page_view` events (initial load + SPA route changes, with
     * referrer, time-on-previous-page and navigation type). The lightweight
     * `observ.session.navigate` marker is unaffected. Default: page views ON.
     */
    disablePageViews?: boolean;
    /**
     * Turn DOM interactions (click / submit / keydown / change / dblclick) into
     * spans, with a `ZoneContextManager` so trace context survives the async work
     * an interaction triggers (e.g. a fetch fired from a click becomes its child).
     *
     * **Opt-in (default off).** It pulls in `zone.js`, which monkey-patches the
     * host's global timers / `Promise` on import; the SDK won't impose that unless
     * asked. The dependency is dynamically imported, so leaving this off keeps both
     * the bundle and the host globals untouched. Enabling it attaches a microtask
     * after `init()` (the zone.js chunk loads asynchronously).
     */
    userInteraction?: boolean;
    /**
     * Gate ALL telemetry behind analytics consent. When `true`, `init()` does
     * nothing — no session, no persistent id, no providers, no network — until
     * consent is present (a cookie or `localStorage` value written by the site's
     * banner, or {@link ObservSdk.grantConsent}). Default: `false` (telemetry driven
     * solely by operator config, the historical behaviour).
     */
    requireConsent?: boolean;
    /** Cookie / `localStorage` key the consent banner writes. Default `observ.consent`. */
    consentKey?: string;
    /**
     * Stored values that count as "granted" (case-insensitive). Default:
     * `['granted', 'true', '1', 'yes', 'all']`. The first entry is what
     * {@link ObservSdk.grantConsent} persists.
     */
    consentGrantedValues?: string[];
}
/** Public SDK handle returned/exposed by the package entry point. */
interface ObservSdk {
    /**
     * Initialize the Observ RUM SDK: establishes the `session.id`, wires OTel RUM
     * tracing (story 1.3) and starts rrweb replay capture (story 2.2, unless
     * `disableReplay`). Idempotent and never throws.
     */
    init(options: ObservInitOptions): void;
    /**
     * Stop replay capture (flushing the residual) and tear down OTel tracing.
     * Best-effort; never throws. Mainly for SPA teardown / tests — the SDK also
     * flushes on `visibilitychange`/`pagehide` on its own.
     */
    shutdown(): Promise<void>;
    /**
     * Attach the authenticated end-user identity to every subsequent span and log
     * (`enduser.id`, + optional `enduser.role`/`enduser.name`). Call after sign-in.
     */
    setUser(user: ObservUser): void;
    /** Clear the authenticated identity (call on sign-out). The pseudo id persists. */
    clearUser(): void;
    /**
     * Grant analytics consent at runtime (e.g. from a consent-banner callback):
     * persists the consent value and immediately starts a `requireConsent` init that
     * was waiting. No-op when nothing is gated. See {@link ObservInitOptions.requireConsent}.
     */
    grantConsent(): void;
    /**
     * Revoke analytics consent: clears the stored consent and shuts the SDK down so
     * it stops emitting (already-sent data cannot be recalled). A later `init()` /
     * {@link ObservSdk.grantConsent} re-arms it.
     */
    revokeConsent(): void;
}

/**
 * Attribute key used everywhere to correlate signals of a single session.
 * Sourced from the pinned `@opentelemetry/semantic-conventions` (incubating
 * `ATTR_SESSION_ID`) rather than a hand-typed literal, so the key tracks the
 * standard. Enforcement rule (architecture): the OTel session attribute is
 * EXACTLY `session.id` — never `sessionId` nor `session_id`. Single source of
 * truth so every signal (spans, semantic events, rrweb) stamps the identical key.
 * A test asserts `=== 'session.id'` to guard that invariant across semconv bumps.
 */
declare const SESSION_ID_ATTRIBUTE: 'session.id';

/**
 * Initialize the Observ RUM SDK.
 *
 *   1. Establishes (or resumes) the visit's `session.id` — the single
 *      correlation key shared by every signal (story 1.2).
 *   2. Wires OTel RUM tracing (story 1.3): `http.client` spans for fetch/XHR,
 *      carrying `session.id`, with W3C `traceparent` propagation and OTLP/HTTP
 *      export to `{endpoint}/v1/traces`.
 *   3. Starts rrweb replay capture (story 2.2): buffered gzip chunks POSTed to
 *      `{endpoint}/v1/replay` (size/time triggered), unless `disableReplay`.
 *   4. Derives semantic events (story 2.3): `click` / `rage_click` / `navigate`
 *      emitted as OTel log records to `{endpoint}/v1/logs` (independent of
 *      `disableReplay`).
 *   5. Captures JS errors (story 2.4): `observ.session.js_error` (uncaught
 *      errors + unhandled rejections) on the same logs channel.
 *
 * Idempotent (a second call re-registers nothing) and never throws — any setup
 * failure is swallowed so the SDK can never break the host page; it degrades to
 * "no tracing / no replay / no semantic events".
 *
 * When `requireConsent` is set, init becomes a GDPR consent barrier: it does
 * nothing (no session, no persistent id, no providers, no network) until consent
 * is present, then auto-starts — watching for a banner that grants consent later
 * (cross-tab via `storage`, same-tab via a light poll) or {@link grantConsent}.
 */
declare function init(options: ObservInitOptions): void;
/**
 * Grant analytics consent at runtime: persist the consent value and immediately
 * start a `requireConsent` init that was waiting. No-op when nothing is gated.
 */
declare function grantConsent(): void;
/**
 * Revoke analytics consent: clear the stored consent (so future inits gate again)
 * and shut the SDK down. Already-sent data cannot be recalled. A later `init()` /
 * {@link grantConsent} re-arms it.
 */
declare function revokeConsent(): void;
/**
 * Stop replay capture (flushing the residual chunk), the semantic-event tap, and
 * tear down OTel tracing + logs. Best-effort and never throws (resolves the
 * story 1.3 "no public teardown" deferral). After this, a later {@link init} can
 * re-start the SDK.
 */
declare function shutdown(): Promise<void>;
/** Singleton SDK handle. Usage: `observ.init({ endpoint, key })`. */
declare const observ: ObservSdk;

export { type ObservInitOptions, type ObservSdk, type ObservUser, SESSION_ID_ATTRIBUTE, clearUser, observ as default, grantConsent, init, observ, revokeConsent, setUser, shutdown };