Add builder for Http::get_entitlements (serenity-rs#2987)

Closes serenity-rs#2983.

src/builder/get_entitlements.rs

@@ -0,0 +1,93 @@
+#[cfg(feature = "http")]
+use crate::http::CacheHttp;
+use crate::internal::prelude::Result;
+use crate::model::id::{EntitlementId, GuildId, SkuId, UserId};
+use crate::model::monetization::Entitlement;
+
+/// Builds a request to fetch active and ended [`Entitlement`]s.
+///
+/// This is a helper for [`Http::get_entitlements`] used via [`Entitlement::list`].
+///
+/// [`Http::get_entitlements`]: crate::http::Http::get_entitlements
+#[derive(Clone, Debug, Default)]
+#[must_use]
+pub struct GetEntitlements {
+    user_id: Option<UserId>,
+    sku_ids: Option<Vec<SkuId>>,
+    before: Option<EntitlementId>,
+    after: Option<EntitlementId>,
+    limit: Option<u8>,
+    guild_id: Option<GuildId>,
+    exclude_ended: Option<bool>,
+}
+
+impl GetEntitlements {
+    /// Filters the returned entitlements by the given [`UserId`].
+    pub fn user_id(mut self, user_id: UserId) -> Self {
+        self.user_id = Some(user_id);
+        self
+    }
+
+    /// Filters the returned entitlements by the given [`SkuId`]s.
+    pub fn sku_ids(mut self, sku_ids: Vec<SkuId>) -> Self {
+        self.sku_ids = Some(sku_ids);
+        self
+    }
+
+    /// Filters the returned entitlements to before the given [`EntitlementId`].
+    pub fn before(mut self, before: EntitlementId) -> Self {
+        self.before = Some(before);
+        self
+    }
+
+    /// Filters the returned entitlements to after the given [`EntitlementId`].
+    pub fn after(mut self, after: EntitlementId) -> Self {
+        self.after = Some(after);
+        self
+    }
+
+    /// Limits the number of entitlements that may be returned.
+    ///
+    /// This is limited to `0..=100`.
+    pub fn limit(mut self, limit: u8) -> Self {
+        self.limit = Some(limit);
+        self
+    }
+
+    /// Filters the returned entitlements by the given [`GuildId`].
+    pub fn guild_id(mut self, guild_id: GuildId) -> Self {
+        self.guild_id = Some(guild_id);
+        self
+    }
+
+    /// Filters the returned entitlements to only active entitlements, if `true`.
+    pub fn exclude_ended(mut self, exclude_ended: bool) -> Self {
+        self.exclude_ended = Some(exclude_ended);
+        self
+    }
+}
+
+#[cfg(feature = "http")]
+#[async_trait::async_trait]
+impl super::Builder for GetEntitlements {
+    type Context<'ctx> = ();
+    type Built = Vec<Entitlement>;
+
+    async fn execute(
+        self,
+        cache_http: impl CacheHttp,
+        _: Self::Context<'_>,
+    ) -> Result<Self::Built> {
+        let http = cache_http.http();
+        http.get_entitlements(
+            self.user_id,
+            self.sku_ids,
+            self.before,
+            self.after,
+            self.limit,
+            self.guild_id,
+            self.exclude_ended,
+        )
+        .await
+    }
+}

src/builder/mod.rs

@@ -75,6 +75,7 @@ mod edit_voice_state;
 mod edit_webhook;
 mod edit_webhook_message;
 mod execute_webhook;
+mod get_entitlements;
 mod get_messages;
 
 pub use add_member::*;
@@ -116,6 +117,7 @@ pub use edit_voice_state::*;
 pub use edit_webhook::*;
 pub use edit_webhook_message::*;
 pub use execute_webhook::*;
+pub use get_entitlements::*;
 pub use get_messages::*;
 
 macro_rules! button_and_select_menu_convenience_methods {

src/model/monetization.rs

@@ -1,3 +1,7 @@
+#[cfg(feature = "model")]
+use crate::builder::{Builder as _, GetEntitlements};
+#[cfg(feature = "model")]
+use crate::http::CacheHttp;
 use crate::model::prelude::*;
 
 /// A premium offering that can be made available to an application's users and guilds.
@@ -105,6 +109,19 @@ impl Entitlement {
             self.application_id, self.sku_id
         )
     }
+
+    /// Returns all entitlements for the current application, active and expired.
+    ///
+    /// # Errors
+    ///
+    /// May error due to an invalid response from discord, or network error.
+    #[cfg(feature = "model")]
+    pub async fn list(
+        cache_http: impl CacheHttp,
+        builder: GetEntitlements,
+    ) -> Result<Vec<Entitlement>> {
+        builder.execute(cache_http, ()).await
+    }
 }
 
 enum_number! {