feat(versions): implement get_project_version function (Retrieves a project version with custom filtering)

feat(versions): add tests related with get_project_version func

chore(versions): docstring changes

Author: nixxoq

src/api/versions.rs

@@ -7,34 +7,20 @@ use crate::{
 };
 
 impl ModrinthAPI {
-    /// Retrieves a list of project versions, optionally filtered, or a single specific version.
+    /// Retrieves a list of project versions with custom filtering.
     ///
     /// # Arguments
     /// * `project_id` - Project slug/id (`&str`).
-    /// * `extra_options` - `Option<ExtraOptions<'_>>`: Optional parameters to filter the list of versions
+    /// * `extra_options` - `Option<ProjectVersionsFilter<'_>>` ([`ProjectVersionsFilter`]): Optional parameters to filter the list of versions
     ///   or to retrieve a specific version.
     ///
     ///   If `extra_options` is `None`, all versions for the project will be returned without any filters.
     ///
-    ///   Fields of `ExtraOptions`:
-    ///
-    ///   - `loaders`: `Option<&[&str]>` - A slice of loader IDs (e.g., `&["forge", "fabric"]`)
-    ///     to filter the list of versions. This is only applied if `number` is `None`.
-    ///     Example: `loaders: Some(&["fabric", "quilt"])`
-    ///
-    ///   - `game_versions`: `Option<&[&str]>` - A slice of game version IDs (e.g., `&["1.19.2", "1.20.1"]`)
-    ///     to filter the list of versions. This is only applied if `number` is `None`.
-    ///     Example: `game_versions: Some(&["1.20.1"])`
-    ///
-    ///   - `featured`: `Option<bool>` - If `Some(true)`, only featured versions will be returned.
-    ///     If `Some(false)`, featured versions will be excluded. If `None`, both featured and
-    ///     non-featured versions are included. This is only applied if `number` is `None`.
-    ///     Example: `featured: Some(true)`
-    ///
     ///   Example usage of `extra_options`:
     ///   ```no_run
-    ///   # use modrinth_api::structs::versions::ExtraOptions;
-    ///   let options_for_filtered_list = ExtraOptions {
+    ///   use modrinth_api::structs::versions::ProjectVersionsFilter;
+    ///
+    ///   let options_for_filtered_list = ProjectVersionsFilter {
     ///       loaders: Some(&["fabric"]),
     ///       game_versions: Some(&["1.20.1"]),
     ///       featured: Some(true),
@@ -49,7 +35,7 @@ impl ModrinthAPI {
     pub async fn get_project_versions(
         &self,
         project_id: &str,
-        extra_options: Option<ExtraOptions<'_>>,
+        extra_options: Option<ProjectVersionsFilter<'_>>,
     ) -> Result<Vec<Version>> {
         check_id_slug(&[project_id])?;
 
@@ -81,35 +67,64 @@ impl ModrinthAPI {
     /// `Result<Version>`:
     /// - `Ok(Version)`: [`Version`] struct.
     /// - `Err(crate::error::Error)`: An error occurred during the API request or data processing.
-    pub async fn get_version(&self, version_id: &str) -> Result<Version> {
+    pub async fn get_version_by_id(&self, version_id: &str) -> Result<Version> {
         check_id_slug(&[version_id])?;
         self.client
             .get(BASE_URL.join_all(vec!["version", version_id]))
             .custom_send_json()
             .await
     }
 
-    //
-    pub async fn version_list_filtered(
+    /// Retrieves a project [`Version`] with custom filtering.
+    ///
+    /// # Arguments
+    /// * `project_id` - Project slug/id (`&str`).
+    /// * `extra_options` - `Option<ProjectVersionParams<'_>>`: Optional parameters to filter the list of versions
+    ///   or to retrieve a specific version.
+    ///
+    ///   If `extra_options` is `None`, all versions for the project will be returned without any filters.
+    ///
+    ///   Example usage of `extra_options`:
+    ///   ```no_run
+    ///   use modrinth_api::structs::versions::ProjectVersionParams;
+    ///   
+    ///   let options_for_filtered_list = ProjectVersionParams {
+    ///       number: Some("mc1.20.1-0.5.13-fabric"), // or Some("OihdIimA")
+    ///       loaders: Some(&["fabric"]),
+    ///       game_versions: Some(&["1.20.1"]),
+    ///       featured: Some(true),
+    ///   };
+    ///   ```
+    ///
+    /// # Returns
+    /// `Result<Vec<Version>>`:
+    /// - `Ok(Vec<Version>)`: A list of the [`Version`] structs. If `number` was specified in `extra_options`,
+    ///   this vector will contain at most one [`Version`] struct.
+    /// - `Err(crate::error::Error)`: An error occurred during the API request or data processing.
+    pub async fn get_project_version(
         &self,
         project_id: &str,
-        loaders: Option<&[&str]>,
-        game_versions: Option<&[&str]>,
-        featured: Option<bool>,
-    ) -> Result<Vec<Version>> {
+        extra_options: Option<ProjectVersionParams<'_>>,
+    ) -> Result<Version> {
         check_id_slug(&[project_id])?;
+
         let mut url = BASE_URL.join_all(vec!["project", project_id, "version"]);
-        if let Some(loaders) = loaders {
-            url = url.with_query_json("loaders", loaders)?;
-        }
-        if let Some(game_versions) = game_versions {
-            url = url.with_query_json("game_versions", game_versions)?;
-        }
-        if let Some(featured) = featured {
-            url = url.with_query_json("featured", featured)?;
+
+        match extra_options {
+            Some(extra_options) => {
+                url = BASE_URL.join_all(vec![
+                    "project",
+                    project_id,
+                    "version",
+                    extra_options.number.unwrap(),
+                ]);
+                url = url.add_optional_query_json("loaders", extra_options.loaders)?;
+                url = url.add_optional_query_json("game_versions", extra_options.game_versions)?;
+                url = url.add_optional_query_json("featured", extra_options.featured)?;
+            }
+            None => {}
         }
 
-        println!("{url}");
         self.client.get(url).custom_send_json().await
     }
 }
@@ -132,7 +147,7 @@ mod tests {
     #[tokio::test]
     async fn get_version_from_project_extra() -> Result<()> {
         let api = ModrinthAPI::default();
-        let options = ExtraOptions {
+        let options = ProjectVersionsFilter {
             loaders: Some(&["fabric"]),
             game_versions: Some(&["1.20.1"]),
             featured: Some(true),
@@ -144,4 +159,34 @@ mod tests {
         assert!(result.unwrap().name.contains("Sodium")); // assume that is Sodium...
         Ok(())
     }
+
+    #[tokio::test]
+    async fn get_single_version_from_project_extra() -> Result<()> {
+        let api = ModrinthAPI::default();
+        let options = ProjectVersionParams {
+            number: Some("mc1.20.1-0.5.13-fabric"),
+            loaders: Some(&["fabric"]),
+            game_versions: Some(&["1.20.1"]),
+            featured: Some(true),
+        };
+        let result = api.get_project_version("AANobbMI", Some(options)).await?;
+
+        assert!(result.name.contains("Sodium")); // assume that is Sodium...
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn get_single_version_from_project_with_wrong_id() -> Result<()> {
+        let api = ModrinthAPI::default();
+        let options = ProjectVersionParams {
+            number: Some("2"),
+            loaders: Some(&["fabric"]),
+            game_versions: Some(&["1.20.1"]),
+            featured: Some(true),
+        };
+        let result = api.get_project_version("AANobbMI", Some(options)).await;
+
+        assert!(result.is_err());
+        Ok(())
+    }
 }