yt-transcript-rs 0.1.1

use crate::errors::CookieError;
use reqwest::cookie::Jar;
use std::path::Path;
use std::sync::Arc;

/// # CookieJarLoader
///
/// Utility for loading and managing cookie jars from Netscape-format cookie files.
///
/// This component provides functionality to load cookies from files, which is necessary
/// for accessing age-restricted YouTube content or when authentication is required.
/// The loader validates cookie file formats and creates properly configured cookie jars
/// that can be used with HTTP requests.
///
/// ## Cookie File Format
///
/// The loader expects cookies in the standard Netscape/Mozilla format:
/// ```text
/// # Netscape HTTP Cookie File
/// # https://curl.se/docs/http-cookies.html
/// # This file was generated by another application
/// .youtube.com   TRUE    /   TRUE    1723157402  SID     AI2OI93JsldfLLPslke93LK
/// .youtube.com   TRUE    /   TRUE    1723231432  HSID    A91JKShflp20Jp2lk34WE
/// ```
///
/// Each line contains tab-separated fields in this order:
/// 1. Domain
/// 2. Flag (whether the cookie can be sent to subdomains)
/// 3. Path
/// 4. Secure flag
/// 5. Expiration timestamp
/// 6. Name
/// 7. Value
///
/// ## Use Cases
///
/// - Accessing age-restricted YouTube videos
/// - Retrieving transcripts from videos that require authentication
/// - Using cookies from a browser session for authenticated requests
///
/// ## Usage with YouTubeTranscriptApi
///
/// ```rust,no_run
/// use std::path::Path;
/// use yt_transcript_rs::YouTubeTranscriptApi;
/// use yt_transcript_rs::CookieJarLoader;
///
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// // Path to your cookie file (exported from a browser)
/// let cookie_path = Path::new("path/to/cookies.txt");
///
/// // Create an API instance with the cookie file
/// let api = YouTubeTranscriptApi::new(
///     Some(&cookie_path),
///     None,  // No proxy
///     None   // Default HTTP client
/// )?;
///
/// // Now you can access age-restricted or authenticated-only content
/// # Ok(())
/// # }
/// ```
pub struct CookieJarLoader;

impl CookieJarLoader {
    /// Loads a cookie jar from a file path.
    ///
    /// This method reads a Netscape-format cookie file, validates its contents,
    /// and creates a cookie jar that can be used with HTTP requests.
    ///
    /// # Parameters
    ///
    /// * `cookie_path` - Path to the Netscape-format cookie file
    ///
    /// # Returns
    ///
    /// * `Result<Jar, CookieError>` - A configured cookie jar or an error
    ///
    /// # Errors
    ///
    /// This method will return a `CookieError` if:
    /// - The file doesn't exist or can't be read (`PathInvalid`)
    /// - The file is empty or doesn't contain valid cookies (`Invalid`)
    /// - The file format doesn't match the expected Netscape format (`Invalid`)
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use std::path::Path;
    /// # use yt_transcript_rs::CookieJarLoader;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let cookie_path = Path::new("cookies.txt");
    /// let jar = CookieJarLoader::load_cookie_jar(&cookie_path)?;
    ///
    /// // Now the jar can be used with a reqwest client
    /// let client = reqwest::Client::builder()
    ///     .cookie_store(true)
    ///     .cookie_provider(std::sync::Arc::new(jar))
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn load_cookie_jar(cookie_path: &Path) -> Result<Jar, CookieError> {
        if !cookie_path.exists() {
            return Err(CookieError::PathInvalid(cookie_path.display().to_string()));
        }

        let content = std::fs::read_to_string(cookie_path)
            .map_err(|_| CookieError::PathInvalid(cookie_path.display().to_string()))?;

        if content.trim().is_empty() {
            return Err(CookieError::Invalid(cookie_path.display().to_string()));
        }

        // Parse the cookie file (expected to be in Netscape format)
        let jar = Jar::default();
        let cookie_lines = content
            .lines()
            .filter(|line| !line.starts_with('#') && !line.trim().is_empty());

        let mut has_cookies = false;

        for line in cookie_lines {
            let parts: Vec<&str> = line.split('\t').collect();
            if parts.len() >= 7 {
                let domain = parts[0];
                let path = parts[2];
                let secure = parts[3] == "TRUE";
                let name = parts[5];
                let value = parts[6];

                let cookie = format!("{}={}", name, value);
                let url = format!(
                    "{}://{}{}",
                    if secure { "https" } else { "http" },
                    domain,
                    path
                );

                jar.add_cookie_str(&cookie, &url.parse().unwrap());
                has_cookies = true;
            }
        }

        if !has_cookies {
            return Err(CookieError::Invalid(cookie_path.display().to_string()));
        }

        Ok(jar)
    }

    /// Creates an Arc-wrapped cookie jar from a file path.
    ///
    /// This is a convenience method that wraps the cookie jar in an `Arc`
    /// (Atomic Reference Counter), which is required by reqwest for thread-safe
    /// cookie handling.
    ///
    /// # Parameters
    ///
    /// * `cookie_path` - Path to the Netscape-format cookie file
    ///
    /// # Returns
    ///
    /// * `Result<Arc<Jar>, CookieError>` - An Arc-wrapped cookie jar or an error
    ///
    /// # Errors
    ///
    /// This method will return a `CookieError` if:
    /// - The file doesn't exist or can't be read (`PathInvalid`)
    /// - The file is empty or doesn't contain valid cookies (`Invalid`)
    /// - The file format doesn't match the expected Netscape format (`Invalid`)
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use std::path::Path;
    /// # use yt_transcript_rs::CookieJarLoader;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let cookie_path = Path::new("cookies.txt");
    ///
    /// // Create an Arc-wrapped jar directly (preferred for use with reqwest)
    /// let jar = CookieJarLoader::create_cookie_jar(&cookie_path)?;
    ///
    /// // Use with a reqwest client
    /// let client = reqwest::Client::builder()
    ///     .cookie_store(true)
    ///     .cookie_provider(jar.clone())
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn create_cookie_jar(cookie_path: &Path) -> Result<Arc<Jar>, CookieError> {
        let jar = Self::load_cookie_jar(cookie_path)?;
        Ok(Arc::new(jar))
    }
}