// Copyright (C) 2026 Jason M. Schwefel. All Rights Reserved.
package com.coldboreballisticsllc.scopedope.data.crash

import com.coldboreballisticsllc.scopedope.ballistics.CrashReporter

/**
 * App-level crash-reporting control surface (SPEC §16.1).
 *
 * Extends the engine's dependency-free [CrashReporter] reporting contract with the
 * Android-side **consent lifecycle**: enabling/disabling at runtime in response to the
 * user's choice (first-run prompt or Settings → Privacy toggle).
 *
 * **Opt-in, OFF by default:** the underlying SDK is initialized only after [enable] is
 * called (which only happens once the user consents). [disable] tears it down so no
 * further data is transmitted for the remainder of the session.
 */
interface CrashReportingController : CrashReporter {
    /** True once the SDK has been initialized this session (i.e. user consented and a DSN exists). */
    val isEnabled: Boolean

    /**
     * Initialize and start crash reporting. No-op if already enabled, if the user has not
     * consented, or if no DSN is configured (empty [SENTRY_DSN] → reporting stays disabled).
     */
    fun enable()

    /** Stop crash reporting and prevent further transmission for the rest of this session. */
    fun disable()
}
