feat: add get_premium_usage endpoint

note: not fully tested; I do not have an account with premium

src/api/users/users.rs

@@ -18,8 +18,8 @@ use crate::{
         AuthorizeConnectionSchema, ConnectionType, CreateUserHarvestSchema,
         DeleteDisableUserSchema, GetPomeloEligibilityReturn, GetPomeloSuggestionsReturn,
         GetRecentMentionsSchema, GetUserProfileSchema, GuildAffinities, Harvest,
-        HarvestBackendType, LimitType, ModifyUserNoteSchema, PublicUser, Snowflake, User,
+        HarvestBackendType, LimitType, ModifyUserNoteSchema, PremiumUsage, PublicUser, Snowflake,
-        UserAffinities, UserModifyProfileSchema, UserModifySchema, UserNote, UserProfile,
+        User, UserAffinities, UserModifyProfileSchema, UserModifySchema, UserNote, UserProfile,
         UserProfileMetadata, UserSettings, VerifyUserEmailChangeResponse,
         VerifyUserEmailChangeSchema,
     },
@@ -614,6 +614,32 @@ impl ChorusUser {
 
         chorus_request.deserialize_response(self).await
     }
+
+    /// Fetches the current user's usage of various premium perks ([PremiumUsage] object).
+    ///
+    /// The local user must have premium (nitro), otherwise the request will fail
+	 /// with a 404 NotFound error and the message {"message": "Premium usage not available", "code": 10084}.
+	 ///
+	 /// # Notes
+	 /// As of 2024/08/16, Spacebar does not yet implement this endpoint.
+    ///
+    /// # Reference
+    /// See <https://docs.discord.sex/resources/user#get-user-premium-usage>
+    pub async fn get_premium_usage(&mut self) -> ChorusResult<PremiumUsage> {
+        let request = Client::new()
+            .get(format!(
+                "{}/users/@me/premium-usage",
+                self.belongs_to.read().unwrap().urls.api,
+            ))
+            .header("Authorization", self.token());
+
+        let chorus_request = ChorusRequest {
+            request,
+            limit_type: LimitType::default(),
+        };
+
+        chorus_request.deserialize_response(self).await
+    }
 }
 
 impl User {

src/types/entities/user.rs

@@ -809,3 +809,47 @@ pub struct GuildAffinity {
     /// The affinity score
     pub affinity: f32,
 }
+
+/// Structure which defines the local user's premium perk usage.
+///
+/// # Reference
+/// See <https://docs.discord.sex/resources/user#get-user-premium-usage>
+#[derive(Debug, Deserialize, Serialize, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct PremiumUsage {
+    /// Number of Nitro stickers the user has sent
+    pub nitro_sticker_sends: PremiumUsageEntry,
+    /// Number of animated emojis the user has sent
+    pub total_animated_emojis: PremiumUsageEntry,
+    /// Number of global emojis the user has sent
+    pub total_global_emojis: PremiumUsageEntry,
+    /// Number of large uploads the user has made
+    pub total_large_uploads: PremiumUsageEntry,
+    /// Number of times the user has streamed in HD
+    pub total_hd_streams: PremiumUsageEntry,
+    /// Number of hours the user has streamed in HD
+    pub hd_hours_streamed: PremiumUsageEntry,
+}
+
+/// Structure for the data in [PremiumUsage].
+///
+/// Currently only contains the number of uses of a premium perk.
+///
+/// # Reference
+/// See <https://docs.discord.sex/resources/user#premium-usage-structure>
+#[derive(Debug, Deserialize, Serialize, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct PremiumUsageEntry {
+    /// Total number of uses for this perk
+    pub value: usize,
+}
+
+impl Into<usize> for PremiumUsageEntry {
+	fn into(self) -> usize {
+	    self.value
+	}
+}
+
+impl From<usize> for PremiumUsageEntry {
+	fn from(value: usize) -> Self {
+	    PremiumUsageEntry { value }
+	}
+}