//! Service trait definitions — use-case interfaces for session management
//! and OAuth flows.
//!
//! These traits define the boundary between the application orchestration
//! layer and the domain. Implementations live in `application/`.
//!
//! # Traits
//!
//! - [`SessionService`] — create, list, archive sessions
//! - [`OAuthService`] — start PKCE flow, complete code exchange, retrieve token
use crate::domain::oauth::{OAuthConfig, OAuthToken};
use crate::domain::session::Session;

/// Session management use-case boundary.
pub trait SessionService {
    /// Create a new session with a generated UUID and the given title.
    fn create_session(&self, title: &str) -> anyhow::Result<Session>;

    /// List all available sessions.
    fn list_all(&self) -> anyhow::Result<Vec<Session>>;

    /// Archive a session by id (sets `archived = true`).
    fn archive_session(&self, id: &str) -> anyhow::Result<()>;
}

/// OAuth flow use-case boundary.
pub trait OAuthService {
    /// Start an OAuth authorization-code + PKCE flow for the given
    /// `redirect_uri` (the caller is responsible for actually listening on
    /// it — e.g. a bound `LoopbackServer`). Returns `(auth_url, state)`:
    /// the URL to send the user to, and the CSRF state token that must be
    /// passed back into `complete_flow` unchanged.
    fn start_flow(
        &self,
        config: &OAuthConfig,
        redirect_uri: &str,
    ) -> anyhow::Result<(String, String)>;

    /// Complete the OAuth flow: validates `state` against the value
    /// persisted during `start_flow` (bailing on mismatch — this is the
    /// CSRF check), then exchanges `code` for a token using the same
    /// `redirect_uri` passed to `start_flow`.
    fn complete_flow(
        &self,
        config: &OAuthConfig,
        redirect_uri: &str,
        code: &str,
        state: &str,
    ) -> anyhow::Result<OAuthToken>;

    /// Retrieve the currently stored OAuth token (if any).
    fn get_token(&self) -> anyhow::Result<Option<OAuthToken>>;
}