feat: support new pin methods

Untested!

Author: AstreaTSS

interactions/api/http/http_requests/channels.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Optional, Sequence, cast, overload
+from typing import TYPE_CHECKING, Any, Optional, Sequence, cast, overload
 
 import discord_typings
 
@@ -491,6 +491,17 @@ async def get_pinned_messages(self, channel_id: "Snowflake_Type") -> list[discor
         result = await self.request(Route("GET", "/channels/{channel_id}/pins", channel_id=channel_id))
         return cast(list[discord_typings.MessageData], result)
 
+    async def paginate_pinned_messages(
+        self,
+        channel_id: "Snowflake_Type",
+        limit: int = 50,
+        before: "Snowflake_Type | None" = None,
+    ) -> dict[str, Any]:
+        return await self.request(
+            Route("GET", "/channels/{channel_id}/messages/pins", channel_id=channel_id),
+            params=dict_filter_none({"before": before, "limit": limit}),
+        )
+
     async def create_stage_instance(
         self,
         channel_id: "Snowflake_Type",

interactions/api/http/http_requests/messages.py

@@ -103,30 +103,51 @@ async def get_message(
         )
         return cast(discord_typings.MessageData, result)
 
-    async def pin_message(self, channel_id: "Snowflake_Type", message_id: "Snowflake_Type") -> None:
+    async def pin_message(
+        self,
+        channel_id: "Snowflake_Type",
+        message_id: "Snowflake_Type",
+        reason: str | None = None,
+    ) -> None:
         """
         Pin a message to a channel.
 
         Args:
             channel_id: Channel to pin message to
             message_id: Message to pin
+            reason: The reason for this action
 
         """
         await self.request(
-            Route("PUT", "/channels/{channel_id}/pins/{message_id}", channel_id=channel_id, message_id=message_id)
+            Route(
+                "PUT", "/channels/{channel_id}/messages/pins/{message_id}", channel_id=channel_id, message_id=message_id
+            ),
+            reason=reason,
         )
 
-    async def unpin_message(self, channel_id: "Snowflake_Type", message_id: "Snowflake_Type") -> None:
+    async def unpin_message(
+        self,
+        channel_id: "Snowflake_Type",
+        message_id: "Snowflake_Type",
+        reason: str | None = None,
+    ) -> None:
         """
         Unpin a message to a channel.
 
         Args:
             channel_id: Channel to unpin message to
             message_id: Message to unpin
+            reason: The reason for this action
 
         """
         await self.request(
-            Route("DELETE", "/channels/{channel_id}/pins/{message_id}", channel_id=channel_id, message_id=message_id)
+            Route(
+                "DELETE",
+                "/channels/{channel_id}/messages/pins/{message_id}",
+                channel_id=channel_id,
+                message_id=message_id,
+            ),
+            reason=reason,
         )
 
     async def edit_message(

interactions/models/discord/channel.py

@@ -164,6 +164,43 @@ async def fetch(self) -> list["GuildForumPost"]:
         raise QueueEmpty
 
 
+class ChannelPins(AsyncIterator):
+    def __init__(self, channel: "BaseChannel", limit: int = 50, before: Snowflake_Type = None) -> None:
+        self.channel: "BaseChannel" = channel
+        self.before: Snowflake_Type = before
+        self._more: bool = True
+        super().__init__(limit)
+
+        if self.before:
+            self.last = self.before
+
+    @property
+    def get_limit(self) -> int:
+        """Get how the maximum number of items that should be retrieved."""
+        return min(self._limit - len(self._retrieved_objects), 50) if self._limit else 50
+
+    async def fetch(self) -> list["Message"]:
+        if self._more:
+            expected = self.get_limit
+
+            rcv = await self.channel._client.http.paginate_pinned_messages(
+                self.channel.id,
+                limit=expected,
+                before=to_snowflake(self.last) if self.last else None,
+            )
+            messages = [
+                self.channel._client.cache.place_message_data({"pinned_at": data["pinned_at"], **data["message"]})
+                for data in rcv["items"]
+            ]
+
+            if not rcv:
+                raise QueueEmpty
+
+            self._more = rcv.get("has_more", False)
+            return messages
+        raise QueueEmpty
+
+
 @attrs.define(eq=False, order=False, hash=False, kw_only=True)
 class PermissionOverwrite(SnowflakeObject, DictSerializationMixin):
     """
@@ -366,8 +403,38 @@ async def fetch_pinned_messages(self) -> List["models.Message"]:
             A list of messages fetched.
 
         """
-        messages_data = await self._client.http.get_pinned_messages(self.id)
-        return [self._client.cache.place_message_data(message_data) for message_data in messages_data]
+        return await ChannelPins(self, limit=0).flatten()
+
+    async def pinned_messages(
+        self,
+        limit: int = 50,
+        before: Snowflake_Type = None,
+    ) -> ChannelPins:
+        """
+        Get an async iterator for the pinned messages in this channel.
+
+        Args:
+            limit: The maximum number of messages to return (set to 0 for no limit), max 50
+            before: get messages before this message ID
+
+        ??? Hint "Example Usage:"
+            ```python
+            async for message in channel.pinned_messages(limit=0):
+                if message.author.id == 174918559539920897:
+                    print("Found author's message")
+                    # ...
+                    break
+            ```
+            or
+            ```python
+            messages = await channel.pinned_messages(limit=50).flatten()
+            ```
+
+        Returns:
+            ChannelPins (AsyncIterator)
+
+        """
+        return ChannelPins(self, limit=limit, before=before)
 
     async def delete_messages(
         self,

interactions/models/discord/message.py

@@ -424,6 +424,10 @@ class Message(BaseMessage):
     """Used for validating a message was sent"""
     pinned: bool = attrs.field(repr=False, default=False)
     """Whether this message is pinned"""
+    pinned_at: Optional["models.Timestamp"] = attrs.field(
+        repr=False, default=None, converter=optional_c(timestamp_converter)
+    )
+    """When this message was pinned, only present when fetching pinned messages"""
     webhook_id: Optional["Snowflake_Type"] = attrs.field(repr=False, default=None, converter=to_optional_snowflake)
     """If the message is generated by a webhook, this is the webhook's id"""
     type: MessageType = attrs.field(repr=False, default=MISSING, converter=optional_c(MessageType))
@@ -929,13 +933,25 @@ async def clear_all_reactions(self) -> None:
         """Clear all emojis from a message."""
         await self._client.http.clear_reactions(self._channel_id, self.id)
 
-    async def pin(self) -> None:
-        """Pin message."""
+    async def pin(self, reason: str | None = None) -> None:
+        """
+        Pin message.
+
+        Args:
+            reason: The optional reason for pinning this message
+
+        """
         await self._client.http.pin_message(self._channel_id, self.id)
         self.pinned = True
 
-    async def unpin(self) -> None:
-        """Unpin message."""
+    async def unpin(self, reason: str | None = None) -> None:
+        """
+        Unpin message.
+
+        Args:
+            reason: The optional reason for unpinning this message
+
+        """
         await self._client.http.unpin_message(self._channel_id, self.id)
         self.pinned = False