qobuz_api_rust/api/content/artists.rs
1use crate::{
2 api::service::QobuzApiService,
3 errors::QobuzApiError::{self},
4 models::{Artist, ReleasesList, SearchResult},
5};
6
7/// Parameters for the artist release list API.
8///
9/// This struct contains all the configurable options for retrieving an artist's releases
10/// from the Qobuz API. It allows for filtering by release type, sorting options, pagination,
11/// and authentication preferences.
12///
13/// # Example
14///
15/// ```
16/// use qobuz_api_rust::api::content::artists::ArtistReleaseListParams;
17///
18/// let params = ArtistReleaseListParams {
19/// with_auth: Some(true),
20/// release_type: Some("album".to_string()),
21/// sort: Some("release_date".to_string()),
22/// order: Some("desc".to_string()),
23/// track_size: Some(5),
24/// limit: Some(20),
25/// offset: Some(0),
26/// };
27/// ```
28#[derive(Default, Debug)]
29pub struct ArtistReleaseListParams {
30 /// Whether to execute the request with authentication (user_auth_token)
31 ///
32 /// When `Some(true)`, the request will be made with the authenticated user's token.
33 /// When `Some(false)` or `None`, the request will be made without authentication.
34 pub with_auth: Option<bool>,
35 /// The type of releases to include in the results
36 ///
37 /// Possible values include "album", "single", "compilation", etc.
38 /// If `None`, all release types will be included.
39 pub release_type: Option<String>,
40 /// The sorting criterion for releases
41 ///
42 /// Common values include "release_date", "title", "popularity", etc.
43 /// If `None`, the default sorting (usually by release date) will be used.
44 pub sort: Option<String>,
45 /// The order direction for sorting
46 ///
47 /// Use "asc" for ascending or "desc" for descending order.
48 /// If `None`, the default order (usually "desc") will be used.
49 pub order: Option<String>,
50 /// The maximum number of tracks to include in each release
51 ///
52 /// This limits how many tracks are returned for each album/single in the results.
53 /// If `None`, defaults to 10 tracks per release.
54 pub track_size: Option<i32>,
55 /// The maximum number of releases to return
56 ///
57 /// Use this to limit the number of releases in the response for pagination.
58 /// If `None`, defaults to 50 releases.
59 pub limit: Option<i32>,
60 /// The offset for pagination
61 ///
62 /// Use this to skip a certain number of releases from the beginning of the results.
63 /// If `None`, defaults to 0 (no offset).
64 pub offset: Option<i32>,
65}
66
67impl QobuzApiService {
68 /// Retrieves detailed information about an artist using their unique ID.
69 ///
70 /// This method fetches comprehensive information about a specific artist from the Qobuz API.
71 /// The response includes basic artist details as well as potentially extended information
72 /// based on the `extra` parameter.
73 ///
74 /// # Arguments
75 ///
76 /// * `artist_id` - The unique identifier of the artist to retrieve
77 /// * `with_auth` - Whether to execute the request with user authentication (optional, defaults to false)
78 /// * `extra` - Additional information to include in the response, such as albums, playlists, etc. (optional)
79 /// * `sort` - How to sort the requested extra information (optional)
80 /// * `limit` - Maximum number of extra results to return (optional, defaults to 50)
81 /// * `offset` - Offset of the first extra result to return (optional, defaults to 0)
82 ///
83 /// # Returns
84 ///
85 /// Returns `Ok(Artist)` containing the artist information if successful, or `Err(QobuzApiError)`
86 /// if the API request fails.
87 ///
88 /// # Example
89 ///
90 /// ```
91 /// # use qobuz_api_rust::QobuzApiService;
92 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
93 /// let service = QobuzApiService::new().await?;
94 /// let artist = service.get_artist("12345", None, Some("albums"), None, None, None).await?;
95 /// println!("Artist name: {:?}", artist.name);
96 /// # Ok(())
97 /// # }
98 /// ```
99 pub async fn get_artist(
100 &self,
101 artist_id: &str,
102 with_auth: Option<bool>,
103 extra: Option<&str>,
104 sort: Option<&str>,
105 limit: Option<i32>,
106 offset: Option<i32>,
107 ) -> Result<Artist, QobuzApiError> {
108 let mut params = vec![("artist_id".to_string(), artist_id.to_string())];
109
110 if let Some(extra_val) = extra {
111 params.push(("extra".to_string(), extra_val.to_string()));
112 }
113
114 if let Some(sort_val) = sort {
115 params.push(("sort".to_string(), sort_val.to_string()));
116 }
117
118 params.push(("limit".to_string(), limit.unwrap_or(50).to_string()));
119 params.push(("offset".to_string(), offset.unwrap_or(0).to_string()));
120
121 let _use_auth = with_auth.unwrap_or(false);
122
123 self.get("/artist/get", ¶ms).await
124 }
125
126 /// Retrieves a list of releases for the specified artist.
127 ///
128 /// This method fetches all releases (albums, singles, etc.) associated with a specific artist.
129 /// The results can be filtered and sorted based on the provided parameters.
130 ///
131 /// # Arguments
132 ///
133 /// * `artist_id` - The unique identifier of the artist whose releases to fetch
134 /// * `params` - Configuration parameters for the request, including filtering, sorting, and pagination options
135 ///
136 /// # Returns
137 ///
138 /// Returns `Ok(ReleasesList)` containing the list of releases if successful, or `Err(QobuzApiError)`
139 /// if the API request fails.
140 ///
141 /// # Example
142 ///
143 /// ```
144 /// # use qobuz_api_rust::QobuzApiService;
145 /// # use qobuz_api_rust::api::content::artists::ArtistReleaseListParams;
146 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
147 /// let service = QobuzApiService::new().await?;
148 /// let params = ArtistReleaseListParams {
149 /// release_type: Some("album".to_string()),
150 /// sort: Some("release_date".to_string()),
151 /// order: Some("desc".to_string()),
152 /// ..Default::default()
153 /// };
154 /// let releases = service.get_release_list("12345", params).await?;
155 /// println!("Found {} releases", releases.items.as_ref().map(|items| items.len()).unwrap_or(0));
156 /// # Ok(())
157 /// # }
158 /// ```
159 pub async fn get_release_list(
160 &self,
161 artist_id: &str,
162 params: ArtistReleaseListParams,
163 ) -> Result<ReleasesList, QobuzApiError> {
164 let mut query_params = vec![("artist_id".to_string(), artist_id.to_string())];
165
166 if let Some(release_type_val) = params.release_type {
167 query_params.push(("release_type".to_string(), release_type_val));
168 }
169
170 if let Some(sort_val) = params.sort {
171 query_params.push(("sort".to_string(), sort_val));
172 }
173
174 if let Some(order_val) = params.order {
175 query_params.push(("order".to_string(), order_val));
176 }
177
178 query_params.push((
179 "track_size".to_string(),
180 params.track_size.unwrap_or(10).to_string(),
181 ));
182 query_params.push(("limit".to_string(), params.limit.unwrap_or(50).to_string()));
183 query_params.push(("offset".to_string(), params.offset.unwrap_or(0).to_string()));
184
185 let _use_auth = params.with_auth.unwrap_or(false);
186
187 self.get("/artist/getReleasesList", &query_params).await
188 }
189
190 /// Searches for artists matching the specified query.
191 ///
192 /// This method performs a text-based search across artist names and other metadata
193 /// to find artists that match the provided query string.
194 ///
195 /// # Arguments
196 ///
197 /// * `query` - The search term to look for in artist names and metadata
198 /// * `limit` - Maximum number of results to return (optional, defaults to 50)
199 /// * `offset` - Offset for pagination (optional, defaults to 0)
200 /// * `with_auth` - Whether to execute the search with user authentication (optional, defaults to false)
201 ///
202 /// # Returns
203 ///
204 /// Returns `Ok(SearchResult)` containing the search results if successful, or `Err(QobuzApiError)`
205 /// if the API request fails.
206 ///
207 /// # Example
208 ///
209 /// ```
210 /// # use qobuz_api_rust::QobuzApiService;
211 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
212 /// let service = QobuzApiService::new().await?;
213 /// let results = service.search_artists("Beatles", Some(10), None, None).await?;
214 /// if let Some(artists) = results.artists {
215 /// println!("Found {} artists", artists.items.as_ref().map(|items| items.len()).unwrap_or(0));
216 /// }
217 /// # Ok(())
218 /// # }
219 /// ```
220 pub async fn search_artists(
221 &self,
222 query: &str,
223 limit: Option<i32>,
224 offset: Option<i32>,
225 with_auth: Option<bool>,
226 ) -> Result<SearchResult, QobuzApiError> {
227 let params = vec![
228 ("query".to_string(), query.to_string()),
229 ("limit".to_string(), limit.unwrap_or(50).to_string()),
230 ("offset".to_string(), offset.unwrap_or(0).to_string()),
231 ];
232
233 let _use_auth = with_auth.unwrap_or(false);
234
235 self.get("/artist/search", ¶ms).await
236 }
237}