feat(client): implement new entitlement endpoint and parameter

changelog/1113.feature.rst

@@ -2,4 +2,4 @@ Support application subscriptions and one-time purchases (see the :ddocs:`offici
 - New types: :class:`SKU`, :class:`Entitlement`.
 - New :attr:`Interaction.entitlements` attribute, and :meth:`InteractionResponse.require_premium` response type.
 - New events: :func:`on_entitlement_create`, :func:`on_entitlement_update`, :func:`on_entitlement_delete`.
-- New :class:`Client` methods: :meth:`~Client.skus`, :meth:`~Client.entitlements`, :meth:`~Client.create_entitlement`.
+- New :class:`Client` methods: :meth:`~Client.skus`, :meth:`~Client.entitlements`, :meth:`~Client.fetch_entitlement`, :meth:`~Client.create_entitlement`.

changelog/1186.feature.rst

@@ -2,4 +2,4 @@ Support application subscriptions and one-time purchases (see the :ddocs:`offici
 - New types: :class:`SKU`, :class:`Entitlement`.
 - New :attr:`Interaction.entitlements` attribute, and :meth:`InteractionResponse.require_premium` response type.
 - New events: :func:`on_entitlement_create`, :func:`on_entitlement_update`, :func:`on_entitlement_delete`.
-- New :class:`Client` methods: :meth:`~Client.skus`, :meth:`~Client.entitlements`, :meth:`~Client.create_entitlement`.
+- New :class:`Client` methods: :meth:`~Client.skus`, :meth:`~Client.entitlements`, :meth:`~Client.fetch_entitlement`, :meth:`~Client.create_entitlement`.

changelog/1249.feature.rst

@@ -0,0 +1,5 @@
+Support application subscriptions and one-time purchases (see the :ddocs:`official docs <monetization/overview>` for more info).
+- New types: :class:`SKU`, :class:`Entitlement`.
+- New :attr:`Interaction.entitlements` attribute, and :meth:`InteractionResponse.require_premium` response type.
+- New events: :func:`on_entitlement_create`, :func:`on_entitlement_update`, :func:`on_entitlement_delete`.
+- New :class:`Client` methods: :meth:`~Client.skus`, :meth:`~Client.entitlements`, :meth:`~Client.fetch_entitlement`, :meth:`~Client.create_entitlement`.

disnake/client.py

@@ -3147,6 +3147,7 @@ def entitlements(
         guild: Optional[Snowflake] = None,
         skus: Optional[Sequence[Snowflake]] = None,
         exclude_ended: bool = False,
+        exclude_deleted: bool = True,
         oldest_first: bool = False,
     ) -> EntitlementIterator:
         """Retrieves an :class:`.AsyncIterator` that enables receiving entitlements for the application.
@@ -3186,6 +3187,8 @@ def entitlements(
             The SKUs for which entitlements are retrieved.
         exclude_ended: :class:`bool`
             Whether to exclude ended/expired entitlements. Defaults to ``False``.
+        exclude_deleted: :class:`bool`
+            Whether to exclude deleted entitlements. Defaults to ``True``.
         oldest_first: :class:`bool`
             If set to ``True``, return entries in oldest->newest order. Defaults to ``False``.
 
@@ -3209,9 +3212,40 @@ def entitlements(
             guild_id=guild.id if guild is not None else None,
             sku_ids=[sku.id for sku in skus] if skus else None,
             exclude_ended=exclude_ended,
+            exclude_deleted=exclude_deleted,
             oldest_first=oldest_first,
         )
 
+    async def fetch_entitlement(self, entitlement_id: int, /) -> Entitlement:
+        """|coro|
+
+        Retrieves a :class:`.Entitlement` for the given ID.
+
+        .. note::
+
+            This method is an API call. To get the entitlements of the invoking user/guild
+            in interactions, consider using :attr:`.Interaction.entitlements`.
+
+        .. versionadded:: 2.10
+
+        Parameters
+        ----------
+        entitlement_id: :class:`int`
+            The ID of the entitlement to retrieve.
+
+        Raises
+        ------
+        HTTPException
+            Retrieving the entitlement failed.
+
+        Returns
+        -------
+        :class:`.Entitlement`
+            The retrieved entitlement.
+        """
+        data = await self.http.get_entitlement(self.application_id, entitlement_id=entitlement_id)
+        return Entitlement(data=data, state=self._connection)
+
     async def create_entitlement(
         self, sku: Snowflake, owner: Union[abc.User, Guild]
     ) -> Entitlement:

disnake/http.py

@@ -2365,10 +2365,12 @@ def get_entitlements(
         guild_id: Optional[Snowflake] = None,
         sku_ids: Optional[SnowflakeList] = None,
         exclude_ended: bool = False,
+        exclude_deleted: bool = False,
     ) -> Response[List[entitlement.Entitlement]]:
         params: Dict[str, Any] = {
             "limit": limit,
             "exclude_ended": int(exclude_ended),
+            "exclude_deleted": int(exclude_deleted),
         }
         if before is not None:
             params["before"] = before
@@ -2386,6 +2388,18 @@ def get_entitlements(
         )
         return self.request(r, params=params)
 
+    def get_entitlement(
+        self, application_id: Snowflake, entitlement_id: int
+    ) -> Response[entitlement.Entitlement]:
+        return self.request(
+            Route(
+                "GET",
+                "/applications/{application_id}/entitlements/{entitlement_id}",
+                application_id=application_id,
+                entitlement_id=entitlement_id,
+            )
+        )
+
     def create_test_entitlement(
         self,
         application_id: Snowflake,

disnake/iterators.py

@@ -1044,6 +1044,7 @@ def __init__(
         before: Optional[Union[Snowflake, datetime.datetime]] = None,
         after: Optional[Union[Snowflake, datetime.datetime]] = None,
         exclude_ended: bool = False,
+        exclude_deleted: bool = True,
         oldest_first: bool = False,
     ) -> None:
         if isinstance(before, datetime.datetime):
@@ -1059,6 +1060,7 @@ def __init__(
         self.guild_id: Optional[int] = guild_id
         self.sku_ids: Optional[List[int]] = sku_ids
         self.exclude_ended: bool = exclude_ended
+        self.exclude_deleted: bool = exclude_deleted
 
         self.state: ConnectionState = state
         self.request = state.http.get_entitlements
@@ -1116,6 +1118,7 @@ async def _before_strategy(self, retrieve: int) -> List[EntitlementPayload]:
             user_id=self.user_id,
             guild_id=self.guild_id,
             exclude_ended=self.exclude_ended,
+            exclude_deleted=self.exclude_deleted,
         )
 
         if len(data):
@@ -1133,6 +1136,7 @@ async def _after_strategy(self, retrieve: int) -> List[EntitlementPayload]:
             user_id=self.user_id,
             guild_id=self.guild_id,
             exclude_ended=self.exclude_ended,
+            exclude_deleted=self.exclude_deleted,
         )
 
         if len(data):