qobuz_api_rust/api/favorites.rs
1use crate::{
2 api::service::QobuzApiService,
3 errors::QobuzApiError::{self, QobuzApiInitializationError},
4 models::{QobuzApiStatusResponse, UserFavorites, UserFavoritesIds},
5};
6
7impl QobuzApiService {
8 /// Add tracks, albums & artists to the authenticated user's favorites.
9 /// At least 1 type of favorite to add is required as parameter.
10 ///
11 /// # Arguments
12 /// * `track_ids` - IDs of the tracks to add, comma separated list (optional)
13 /// * `album_ids` - IDs of the albums to add, comma separated list (optional)
14 /// * `artist_ids` - IDs of the artists to add, comma separated list (optional)
15 ///
16 /// # Returns
17 /// * `Ok(QobuzApiStatusResponse)` - Response indicating if the request was successful
18 /// * `Err(QobuzApiError)` - If the API request fails
19 ///
20 /// # Example
21 /// ```rust,no_run
22 /// # use qobuz_api_rust::QobuzApiService;
23 /// # use tokio;
24 /// # #[tokio::main]
25 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
26 /// # let service = QobuzApiService::new().await?;
27 /// // Add a track to favorites
28 /// let response = service.add_user_favorites(
29 /// Some("123456789"),
30 /// None,
31 /// None,
32 /// ).await?;
33 /// # Ok(())
34 /// # }
35 /// ```
36 pub async fn add_user_favorites(
37 &self,
38 track_ids: Option<&str>,
39 album_ids: Option<&str>,
40 artist_ids: Option<&str>,
41 ) -> Result<QobuzApiStatusResponse, QobuzApiError> {
42 let mut params = Vec::new();
43
44 if let Some(ids) = track_ids {
45 params.push(("track_ids".to_string(), ids.to_string()));
46 }
47
48 if let Some(ids) = album_ids {
49 params.push(("album_ids".to_string(), ids.to_string()));
50 }
51
52 if let Some(ids) = artist_ids {
53 params.push(("artist_ids".to_string(), ids.to_string()));
54 }
55
56 // At least one type of favorite must be provided
57 if params.is_empty() {
58 return Err(QobuzApiInitializationError {
59 message: "At least one type of favorite (track_ids, album_ids, or artist_ids) must be provided".to_string(),
60 });
61 }
62
63 self.signed_get("/favorite/create", ¶ms).await
64 }
65
66 /// Removes tracks, albums & artists from the authenticated user's favorites.
67 /// At least 1 type of favorite to remove is required as parameter.
68 ///
69 /// # Arguments
70 /// * `track_ids` - IDs of the tracks to remove, comma separated list (optional)
71 /// * `album_ids` - IDs of the albums to remove, comma separated list (optional)
72 /// * `artist_ids` - IDs of the artists to remove, comma separated list (optional)
73 ///
74 /// # Returns
75 /// * `Ok(QobuzApiStatusResponse)` - Response indicating if the request was successful
76 /// * `Err(QobuzApiError)` - If the API request fails
77 ///
78 /// # Example
79 /// ```rust,no_run
80 /// # use qobuz_api_rust::QobuzApiService;
81 /// # use tokio;
82 /// # #[tokio::main]
83 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
84 /// # let service = QobuzApiService::new().await?;
85 /// // Remove a track from favorites
86 /// let response = service.delete_user_favorites(
87 /// Some("123456789"),
88 /// None,
89 /// None,
90 /// ).await?;
91 /// # Ok(())
92 /// # }
93 /// ```
94 pub async fn delete_user_favorites(
95 &self,
96 track_ids: Option<&str>,
97 album_ids: Option<&str>,
98 artist_ids: Option<&str>,
99 ) -> Result<QobuzApiStatusResponse, QobuzApiError> {
100 let mut params = Vec::new();
101
102 if let Some(ids) = track_ids {
103 params.push(("track_ids".to_string(), ids.to_string()));
104 }
105
106 if let Some(ids) = album_ids {
107 params.push(("album_ids".to_string(), ids.to_string()));
108 }
109
110 if let Some(ids) = artist_ids {
111 params.push(("artist_ids".to_string(), ids.to_string()));
112 }
113
114 // At least one type of favorite must be provided
115 if params.is_empty() {
116 return Err(QobuzApiInitializationError {
117 message: "At least one type of favorite (track_ids, album_ids, or artist_ids) must be provided".to_string(),
118 });
119 }
120
121 self.signed_get("/favorite/delete", ¶ms).await
122 }
123
124 /// Gets the IDs of the user favorites for the authenticated user or user with the specified user ID.
125 ///
126 /// # Arguments
127 /// * `user_id` - The User ID to fetch the favorites from. If omitted, returns favorites of the logged in user using user_auth_token (optional)
128 /// * `limit` - The maximum number of extra results to return. Defaults to 5000, minimum 1, maximum 99999 (optional)
129 /// * `offset` - The offset of the first extra result to return. Defaults to 0 (optional)
130 ///
131 /// # Returns
132 /// * `Ok(UserFavoritesIds)` - The IDs of the user favorites
133 /// * `Err(QobuzApiError)` - If the API request fails
134 ///
135 /// # Example
136 /// ```rust,no_run
137 /// # use qobuz_api_rust::QobuzApiService;
138 /// # use tokio;
139 /// # #[tokio::main]
140 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
141 /// # let service = QobuzApiService::new().await?;
142 /// // Get favorite IDs with default parameters
143 /// let favorites = service.get_user_favorite_ids(None, None, None).await?;
144 ///
145 /// // Get favorite IDs with custom parameters
146 /// let favorites = service.get_user_favorite_ids(
147 /// Some("123456789"),
148 /// Some(100),
149 /// Some(50),
150 /// ).await?;
151 /// # Ok(())
152 /// # }
153 /// ```
154 pub async fn get_user_favorite_ids(
155 &self,
156 user_id: Option<&str>,
157 limit: Option<i32>,
158 offset: Option<i32>,
159 ) -> Result<UserFavoritesIds, QobuzApiError> {
160 let mut params = Vec::new();
161
162 if let Some(id) = user_id {
163 params.push(("user_id".to_string(), id.to_string()));
164 }
165
166 params.push(("limit".to_string(), limit.unwrap_or(5000).to_string()));
167 params.push(("offset".to_string(), offset.unwrap_or(0).to_string()));
168
169 self.signed_get("/favorite/getUserFavoriteIds", ¶ms)
170 .await
171 }
172
173 /// Gets user favorites of the authenticated user or user with the specified user ID.
174 ///
175 /// # Arguments
176 /// * `user_id` - The User ID to fetch the favorites from. If omitted, returns favorites of the logged in user using user_auth_token (optional)
177 /// * `type_param` - Type of favorites to include in the response (optional). Possible values are 'tracks', 'albums', 'artists' & 'articles'. If no type defined, all types are returned
178 /// * `limit` - The maximum number of extra results to return. Defaults to 50, minimum 1, maximum 500 (optional)
179 /// * `offset` - The offset of the first extra result to return. Defaults to 0 (optional)
180 ///
181 /// # Returns
182 /// * `Ok(UserFavorites)` - The user favorites
183 /// * `Err(QobuzApiError)` - If the API request fails
184 ///
185 /// # Example
186 /// ```rust,no_run
187 /// # use qobuz_api_rust::QobuzApiService;
188 /// # use tokio;
189 /// # #[tokio::main]
190 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
191 /// # let service = QobuzApiService::new().await?;
192 /// // Get all favorite types with default parameters
193 /// let favorites = service.get_user_favorites(None, None, None, None).await?;
194 ///
195 /// // Get only favorite albums with custom parameters
196 /// let album_favorites = service.get_user_favorites(
197 /// None,
198 /// Some("albums"),
199 /// Some(100),
200 /// Some(20),
201 /// ).await?;
202 /// # Ok(())
203 /// # }
204 /// ```
205 pub async fn get_user_favorites(
206 &self,
207 user_id: Option<&str>,
208 type_param: Option<&str>,
209 limit: Option<i32>,
210 offset: Option<i32>,
211 ) -> Result<UserFavorites, QobuzApiError> {
212 let mut params = Vec::new();
213
214 if let Some(id) = user_id {
215 params.push(("user_id".to_string(), id.to_string()));
216 }
217
218 if let Some(t) = type_param {
219 params.push(("type".to_string(), t.to_string()));
220 }
221
222 params.push(("limit".to_string(), limit.unwrap_or(50).to_string()));
223 params.push(("offset".to_string(), offset.unwrap_or(0).to_string()));
224
225 self.signed_get("/favorite/getUserFavorites", ¶ms).await
226 }
227}