comdirect_rest_api/

session.rs

use std::future::Future;
use std::sync::Arc;
use std::time::Duration;

use crate::application::session_runtime::{
    RefreshTokenCallback, SessionRuntime, SessionRuntimeConfig, StateChangeCallback,
};
use crate::auth::{LoginChallenge, TanAction};
use crate::error::Result;
use crate::types::SessionStateType;

const DEFAULT_BASE_URL: &str = "https://api.comdirect.de";

/// Configuration used to create a [`Session`].
///
/// The configuration separates static credentials from runtime concerns such as
/// timeouts and token refresh behavior. This keeps all I/O settings in one
/// location and avoids hidden defaults spread across modules.
///
/// # Example
///
/// ```no_run
/// use comdirect_rest_api::{Session, SessionConfig};
///
/// # async fn demo() -> Result<(), comdirect_rest_api::ComdirectError> {
/// let config = SessionConfig::new("client-id", "client-secret", "username", "pin")
///     .with_base_url("https://api.comdirect.de")
///     .with_request_timeout(std::time::Duration::from_secs(20))
///     .with_refresh_buffer(std::time::Duration::from_secs(90));
///
/// let session = Session::from_config(config)?;
/// session.try_restore("persisted-refresh-token").await?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct SessionConfig {
    client_id: String,
    client_secret: String,
    username: String,
    password: String,
    base_url: String,
    request_timeout: Duration,
    refresh_buffer: Duration,
}

impl SessionConfig {
    /// Creates configuration with production defaults.
    pub fn new(
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
        username: impl Into<String>,
        password: impl Into<String>,
    ) -> Self {
        Self {
            client_id: client_id.into(),
            client_secret: client_secret.into(),
            username: username.into(),
            password: password.into(),
            base_url: DEFAULT_BASE_URL.to_string(),
            request_timeout: Duration::from_secs(30),
            refresh_buffer: Duration::from_secs(60),
        }
    }

    /// Overrides the API base URL.
    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
        self.base_url = base_url.into();
        self
    }

    /// Overrides the request timeout used for all HTTP calls.
    pub fn with_request_timeout(mut self, request_timeout: Duration) -> Self {
        self.request_timeout = request_timeout;
        self
    }

    /// Configures how early token refresh should happen before expiry.
    pub fn with_refresh_buffer(mut self, refresh_buffer: Duration) -> Self {
        self.refresh_buffer = refresh_buffer;
        self
    }
}

/// Stateful comdirect API session with automatic token refresh.
///
/// The session encapsulates auth orchestration, transient-error retries,
/// background refresh supervision, and endpoint access.
///
/// # Example
///
/// ```no_run
/// use comdirect_rest_api::{Session, TanAction};
///
/// # async fn demo() -> Result<(), comdirect_rest_api::ComdirectError> {
/// let session = Session::new("client-id", "client-secret", "username", "pin")?;
///
/// session
///     .login(|challenge| async move {
///         println!("challenge {}", challenge.challenge_id);
///         TanAction::ConfirmPushTan
///     })
///     .await?;
///
/// let balances = session.accounts().get_balances().await?;
/// println!("{} accounts", balances.values.len());
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct Session {
    username: String,
    runtime: Arc<SessionRuntime>,
}

impl Session {
    /// Creates a session using default runtime settings.
    pub fn new(
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
        username: impl Into<String>,
        password: impl Into<String>,
    ) -> Result<Self> {
        let config = SessionConfig::new(client_id, client_secret, username, password);
        Self::from_config(config)
    }

    /// Creates a session from explicit [`SessionConfig`].
    pub fn from_config(config: SessionConfig) -> Result<Self> {
        let username = config.username.clone();
        let runtime = Arc::new(SessionRuntime::new(SessionRuntimeConfig {
            base_url: config.base_url,
            client_id: config.client_id,
            client_secret: config.client_secret,
            username: config.username,
            password: config.password,
            request_timeout: config.request_timeout,
            refresh_buffer_secs: config.refresh_buffer.as_secs(),
        })?);

        Ok(Self { username, runtime })
    }

    /// Returns a copyable endpoint client for account operations.
    pub fn accounts(&self) -> crate::accounts::AccountsApi {
        crate::accounts::AccountsApi::new(self.clone())
    }

    /// Returns a copyable endpoint client for brokerage operations.
    pub fn brokerage(&self) -> crate::brokerage::BrokerageApi {
        crate::brokerage::BrokerageApi::new(self.clone())
    }

    /// Registers a callback invoked on session state transitions.
    pub async fn set_state_change_callback<F>(&self, callback: F)
    where
        F: Fn(SessionStateType, SessionStateType) + Send + Sync + 'static,
    {
        self.runtime
            .set_state_change_callback(Some(Arc::new(callback) as Arc<StateChangeCallback>))
            .await;
    }

    /// Registers a callback invoked whenever a new refresh token is issued.
    pub async fn set_refresh_token_callback<F>(&self, callback: F)
    where
        F: Fn(String) + Send + Sync + 'static,
    {
        self.runtime
            .set_refresh_token_callback(Some(Arc::new(callback) as Arc<RefreshTokenCallback>))
            .await;
    }

    /// Reads the current authorization state.
    pub async fn state(&self) -> SessionStateType {
        self.runtime.state().await
    }

    /// Performs non-interactive login using a persisted refresh token.
    ///
    /// This is the preferred startup path for long-running services because it
    /// avoids interactive TAN prompts during cold start.
    pub async fn try_restore(&self, refresh_token: &str) -> Result<()> {
        self.runtime.login_try(refresh_token).await
    }

    /// Performs interactive login and asks the callback how to answer TAN challenges.
    ///
    /// Use this for initial bootstrap of refresh tokens. Persist the refresh
    /// token from `set_refresh_token_callback` and switch to [`Self::try_restore`]
    /// for subsequent restarts.
    pub async fn login<F, Fut>(&self, callback: F) -> Result<()>
    where
        F: Fn(LoginChallenge) -> Fut + Send + Sync,
        Fut: Future<Output = TanAction> + Send,
    {
        self.runtime.login(callback).await
    }

    /// Stops background refresh tasks and marks the session unauthorized.
    ///
    /// Call this before process shutdown to ensure refresh workers are cancelled
    /// deterministically.
    pub async fn shutdown(&self) {
        self.runtime.shutdown().await;
    }

    #[cfg(feature = "web")]
    /// Mounts HTTP login routes for browser-driven TAN flows.
    pub async fn login_web(self: Arc<Self>, router: axum::Router) -> axum::Router {
        crate::web::mount_session_login_route(router, "/comdirect", self.username.clone(), self)
            .await
    }

    pub(crate) async fn get_authorized_resource(
        &self,
        operation: &'static str,
        api_path: &str,
    ) -> Result<String> {
        self.runtime
            .get_authorized_resource(operation, api_path)
            .await
    }
}