feat: application role connections (#1791)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Lala Sabathil <[email protected]>
Co-authored-by: Dorukyum <[email protected]>

Author: 4 people

CHANGELOG.md

@@ -17,6 +17,10 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#1809](https://github.com/Pycord-Development/pycord/pull/1809))
 - Added missing `image` parameter to `Guild.create_scheduled_event()` method.
   ([#1831](https://github.com/Pycord-Development/pycord/pull/1831))
+- New `ApplicationRoleConnectionMetadata` class for application role connection
+  metadata, along with the `fetch_role_connection_metadata_records` and
+  `update_role_connection_metadata_records` methods in `Client`.
+  ([#1791](https://github.com/Pycord-Development/pycord/pull/1791))
 - Added new message types, `interaction_premium_upsell`, `stage_start`, `stage_end`,
   `stage_speaker`, `stage_raise_hand`, `stage_topic`, and
   `guild_application_premium_subscription`.

discord/__init__.py

@@ -27,6 +27,7 @@
 from . import abc, opus, sinks, ui, utils
 from .activity import *
 from .appinfo import *
+from .application_role_connection import *
 from .asset import *
 from .audit_logs import *
 from .automod import *

discord/application_role_connection.py

@@ -0,0 +1,128 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .enums import ApplicationRoleConnectionMetadataType, try_enum
+from .utils import MISSING
+
+if TYPE_CHECKING:
+    from .types.application_role_connection import (
+        ApplicationRoleConnectionMetadata as ApplicationRoleConnectionMetadataPayload,
+    )
+
+__all__ = ("ApplicationRoleConnectionMetadata",)
+
+
+class ApplicationRoleConnectionMetadata:
+    r"""Represents role connection metadata for a Discord application.
+
+    .. versionadded:: 2.4
+
+    Parameters
+    ----------
+    type: :class:`ApplicationRoleConnectionMetadataType`
+        The type of metadata value.
+    key: :class:`str`
+        The key for this metadata field.
+        May only be the ``a-z``, ``0-9``, or ``_`` characters, with a maximum of 50 characters.
+    name: :class:`str`
+        The name for this metadata field. Maximum 100 characters.
+    description: :class:`str`
+        The description for this metadata field. Maximum 200 characters.
+    name_localizations: Optional[Dict[:class:`str`, :class:`str`]]
+        The name localizations for this metadata field. The values of this should be ``"locale": "name"``.
+        See `here <https://discord.com/developers/docs/reference#locales>`_ for a list of valid locales.
+    description_localizations: Optional[Dict[:class:`str`, :class:`str`]]
+        The description localizations for this metadata field. The values of this should be ``"locale": "name"``.
+        See `here <https://discord.com/developers/docs/reference#locales>`_ for a list of valid locales.
+    """
+
+    __slots__ = (
+        "type",
+        "key",
+        "name",
+        "description",
+        "name_localizations",
+        "description_localizations",
+    )
+
+    def __init__(
+        self,
+        *,
+        type: ApplicationRoleConnectionMetadataType,
+        key: str,
+        name: str,
+        description: str,
+        name_localizations: dict[str, str] = MISSING,
+        description_localizations: dict[str, str] = MISSING,
+    ):
+        self.type: ApplicationRoleConnectionMetadataType = type
+        self.key: str = key
+        self.name: str = name
+        self.name_localizations: dict[str, str] = name_localizations
+        self.description: str = description
+        self.description_localizations: dict[str, str] = description_localizations
+
+    def __repr__(self):
+        return (
+            f"<ApplicationRoleConnectionMetadata "
+            f"type={self.type!r} "
+            f"key={self.key!r} "
+            f"name={self.name!r} "
+            f"description={self.description!r} "
+            f"name_localizations={self.name_localizations!r} "
+            f"description_localizations={self.description_localizations!r}>"
+        )
+
+    def __str__(self):
+        return self.name
+
+    @classmethod
+    def from_dict(
+        cls, data: ApplicationRoleConnectionMetadataPayload
+    ) -> ApplicationRoleConnectionMetadata:
+        return cls(
+            type=try_enum(ApplicationRoleConnectionMetadataType, data["type"]),
+            key=data["key"],
+            name=data["name"],
+            description=data["description"],
+            name_localizations=data.get("name_localizations"),
+            description_localizations=data.get("description_localizations"),
+        )
+
+    def to_dict(self) -> ApplicationRoleConnectionMetadataPayload:
+        data = {
+            "type": self.type.value,
+            "key": self.key,
+            "name": self.name,
+            "description": self.description,
+        }
+        if self.name_localizations is not MISSING:
+            data["name_localizations"] = self.name_localizations
+        if self.description_localizations is not MISSING:
+            data["description_localizations"] = self.description_localizations
+        return data

discord/client.py

@@ -37,6 +37,7 @@
 from . import utils
 from .activity import ActivityTypes, BaseActivity, create_activity
 from .appinfo import AppInfo, PartialAppInfo
+from .application_role_connection import ApplicationRoleConnectionMetadata
 from .backoff import ExponentialBackoff
 from .channel import PartialMessageable, _threaded_channel_factory
 from .emoji import Emoji
@@ -1782,3 +1783,47 @@ def persistent_views(self) -> Sequence[View]:
         .. versionadded:: 2.0
         """
         return self._connection.persistent_views
+
+    async def fetch_role_connection_metadata_records(
+        self,
+    ) -> list[ApplicationRoleConnectionMetadata]:
+        """|coro|
+
+        Fetches the bot's role connection metadata records.
+
+        .. versionadded:: 2.4
+
+        Returns
+        -------
+        List[:class:`.ApplicationRoleConnectionMetadata`]
+            The bot's role connection metadata records.
+        """
+        data = await self._connection.http.get_application_role_connection_metadata_records(
+            self.application_id
+        )
+        return [ApplicationRoleConnectionMetadata.from_dict(r) for r in data]
+
+    async def update_role_connection_metadata_records(
+        self, *role_connection_metadata
+    ) -> list[ApplicationRoleConnectionMetadata]:
+        """|coro|
+
+        Updates the bot's role connection metadata records.
+
+        .. versionadded:: 2.4
+
+        Parameters
+        ----------
+        *role_connection_metadata: :class:`ApplicationRoleConnectionMetadata`
+            The new metadata records to send to Discord.
+
+        Returns
+        -------
+        List[:class:`.ApplicationRoleConnectionMetadata`]
+            The updated role connection metadata records.
+        """
+        payload = [r.to_dict() for r in role_connection_metadata]
+        data = await self._connection.http.update_application_role_connection_metadata_records(
+            self.application_id, payload
+        )
+        return [ApplicationRoleConnectionMetadata.from_dict(r) for r in data]

discord/enums.py

@@ -67,6 +67,7 @@
     "AutoModEventType",
     "AutoModActionType",
     "AutoModKeywordPresetType",
+    "ApplicationRoleConnectionMetadataType",
 )
 
 
@@ -930,6 +931,19 @@ class AutoModKeywordPresetType(Enum):
     slurs = 3
 
 
+class ApplicationRoleConnectionMetadataType(Enum):
+    """Application role connection metadata type"""
+
+    integer_less_than_or_equal = 1
+    integer_greater_than_or_equal = 2
+    integer_equal = 3
+    integer_not_equal = 4
+    datetime_less_than_or_equal = 5
+    datetime_greater_than_or_equal = 6
+    boolean_equal = 7
+    boolean_not_equal = 8
+
+
 T = TypeVar("T")
 
 

discord/http.py

@@ -56,6 +56,7 @@
     from .file import File
     from .types import (
         appinfo,
+        application_role_connection,
         audit_log,
         automod,
         channel,
@@ -2818,6 +2819,31 @@ def bulk_edit_guild_application_command_permissions(
         )
         return self.request(r, json=payload)
 
+    # Application Role Connections
+
+    def get_application_role_connection_metadata_records(
+        self,
+        application_id: Snowflake,
+    ) -> Response[list[application_role_connection.ApplicationRoleConnectionMetadata]]:
+        r = Route(
+            "GET",
+            "/applications/{application_id}/role-connections/metadata",
+            application_id=application_id,
+        )
+        return self.request(r)
+
+    def update_application_role_connection_metadata_records(
+        self,
+        application_id: Snowflake,
+        payload: list[application_role_connection.ApplicationRoleConnectionMetadata],
+    ) -> Response[list[application_role_connection.ApplicationRoleConnectionMetadata]]:
+        r = Route(
+            "PUT",
+            "/applications/{application_id}/role-connections/metadata",
+            application_id=application_id,
+        )
+        return self.request(r, json=payload)
+
     # Misc
 
     def application_info(self) -> Response[appinfo.AppInfo]:

discord/types/application_role_connection.py

@@ -0,0 +1,40 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .._typed_dict import NotRequired, TypedDict
+
+ApplicationRoleConnectionMetadataType = Literal[1, 2, 3, 4, 5, 6, 7, 8]
+
+
+class ApplicationRoleConnectionMetadata(TypedDict):
+    type: ApplicationRoleConnectionMetadataType
+    key: str
+    name: str
+    name_localizations: NotRequired[dict[str, str]]
+    description: str
+    description_localizations: NotRequired[dict[str, str]]

docs/api/data_classes.rst

@@ -154,3 +154,11 @@ Permissions
 
 .. autoclass:: PermissionOverwrite
     :members:
+
+Application Role Connections
+-----------------------------
+
+.. attributetable:: ApplicationRoleConnectionMetadata
+
+.. autoclass:: ApplicationRoleConnectionMetadata
+    :members:

docs/api/enums.rst

@@ -2056,6 +2056,51 @@ of :class:`enum.Enum`.
 
         Represents a scheduled event that is only available to members inside the guild.
 
+.. class:: ApplicationRoleConnectionMetadataType
+
+    Represents an application role connection metadata type.
+
+    Each metadata type offers a comparison operation that allows guilds to
+    configure role requirements based on metadata values stored by the bot.
+    Bots specify a ``metadata value`` for each user and guilds specify the
+    required ``guild's configured value`` within the guild role settings.
+
+    .. versionadded:: 2.4
+
+    .. attribute:: integer_less_than_or_equal
+
+        The metadata value (``integer``) is less than or equal to the guild's configured value (``integer``).
+
+    .. attribute:: integer_greater_than_or_equal
+
+        The metadata value (``integer``) is greater than or equal to the guild's configured value (``integer``).
+
+    .. attribute:: integer_equal
+
+        The metadata value (``integer``) is equal to the guild's configured value (``integer``).
+
+    .. attribute:: integer_not_equal
+
+        The metadata value (``integer``) is not equal to the guild's configured value (``integer``).
+
+    .. attribute:: datetime_less_than_or_equal
+
+        The metadata value (``datetime``) is less than or equal to the guild's configured value
+        (``integer``; the number of days before the current date).
+
+    .. attribute:: datetime_greater_than_or_equal
+
+        The metadata value (``datetime``) is greater than or equal to the guild's configured value
+        (``integer``; the number of days before the current date).
+
+    .. attribute:: boolean_equal
+
+        The metadata value (``integer``) is equal to the guild's configured value (``integer``; 1).
+
+    .. attribute:: boolean_not_equal
+
+        The metadata value (``integer``) is not equal to the guild's configured value (``integer``; 1).
+
 .. class:: AutoModTriggerType
 
     Represents an AutoMod trigger type.