feat: add incident management functionality to guilds

Author: Lumabots

discord/__init__.py

@@ -56,6 +56,7 @@
 from .monetization import *
 from .object import *
 from .onboarding import *
+from .incidents import *
 from .partial_emoji import *
 from .permissions import *
 from .player import *

discord/guild.py

@@ -26,6 +26,7 @@
 from __future__ import annotations
 
 import copy
+import datetime
 import unicodedata
 from typing import (
     TYPE_CHECKING,
@@ -80,6 +81,7 @@
 from .mixins import Hashable
 from .monetization import Entitlement
 from .onboarding import Onboarding
+from .incidents import IncidentsData
 from .permissions import PermissionOverwrite
 from .role import Role, RoleColours
 from .scheduled_events import ScheduledEvent, ScheduledEventLocation
@@ -111,7 +113,10 @@
     from .state import ConnectionState
     from .template import Template
     from .types.guild import Ban as BanPayload
-    from .types.guild import Guild as GuildPayload
+    from .types.guild import (
+        Guild as GuildPayload,
+        IncidentsData as IncidentsDataPayload,
+    )
     from .types.guild import GuildFeature, MFALevel
     from .types.member import Member as MemberPayload
     from .types.threads import Thread as ThreadPayload
@@ -290,6 +295,7 @@ class Guild(Hashable):
         "approximate_member_count",
         "approximate_presence_count",
         "_sounds",
+        "incidents",
     )
 
     _PREMIUM_GUILD_LIMITS: ClassVar[dict[int | None, _GuildLimit]] = {
@@ -569,6 +575,13 @@ def _from_data(self, guild: GuildPayload) -> None:
             sound = SoundboardSound(state=state, http=state.http, data=sound)
             self._add_sound(sound)
 
+        incidents_payload = guild.get("incidents_data")
+        self.incidents: IncidentsData | None = (
+            IncidentsData(data=incidents_payload, guild=self)
+            if incidents_payload is not None
+            else None
+        )
+
     def _add_sound(self, sound: SoundboardSound) -> None:
         self._sounds[sound.id] = sound
         self._state._add_sound(sound)
@@ -4405,6 +4418,52 @@ async def edit_onboarding(
         new = await self._state.http.edit_onboarding(self.id, fields, reason=reason)
         return Onboarding(data=new, guild=self)
 
+    async def modify_incident_actions(
+        self,
+        *,
+        invites_disabled_until: datetime.datetime | None = MISSING,
+        dms_disabled_until: datetime.datetime | None = MISSING,
+        reason: str | None = MISSING,
+    ) -> IncidentsData:
+        """|coro|
+
+        Modify the guild's incident actions (invites or DMs disabled until a
+        given ISO8601 timestamp). Supplying ``None`` disables the respective
+        action. Requires :attr:`~Permissions.manage_guild`.
+
+        Parameters
+        ----------
+        invites_disabled_until: Optional[:class:`str`]
+            ISO8601 timestamp indicating when invites will be enabled again, or
+            ``None`` to disable.
+        dms_disabled_until: Optional[:class:`str`]
+            ISO8601 timestamp indicating when DMs will be enabled again, or
+            ``None`` to disable.
+        reason: Optional[:class:`str`]
+            Audit log reason.
+
+        Returns
+        -------
+        :class:`IncidentsData`
+            The updated incidents data for the guild.
+        """
+
+        fields: IncidentsDataPayload = {}
+        if invites_disabled_until is not MISSING:
+            fields["invites_disabled_until"] = (
+                invites_disabled_until and invites_disabled_until.isoformat()
+            )
+
+        if dms_disabled_until is not MISSING:
+            fields["dms_disabled_until"] = (
+                dms_disabled_until and dms_disabled_until.isoformat()
+            )
+
+        new = await self._state.http.modify_guild_incident_actions(
+            self.id, fields, reason=reason
+        )
+        return IncidentsData(data=new, guild=self)
+
     async def delete_auto_moderation_rule(
         self,
         id: int,

discord/http.py

@@ -47,7 +47,7 @@
 from .file import VoiceMessage
 from .gateway import DiscordClientWebSocketResponse
 from .soundboard import PartialSoundboardSound, SoundboardSound
-from .utils import MISSING, warn_deprecated
+from .utils import MISSING
 
 _log = logging.getLogger(__name__)
 
@@ -3135,6 +3135,19 @@ def edit_onboarding(
             reason=reason,
         )
 
+    def modify_guild_incident_actions(
+        self,
+        guild_id: Snowflake,
+        payload: guild.IncidentsData,
+        *,
+        reason: str | None = None,
+    ) -> Response[guild.IncidentsData]:
+        return self.request(
+            Route("PUT", "/guilds/{guild_id}/incident-actions", guild_id=guild_id),
+            json=payload,
+            reason=reason,
+        )
+
     # Polls
 
     def expire_poll(

discord/incidents.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .guild import Guild
+    from .types.guild import IncidentsData as IncidentsDataPayload
+
+__all__ = ("IncidentsData",)
+
+
+class IncidentsData:
+    """Represents the incidents data object for a guild.
+
+    Attributes
+    ----------
+    invites_disabled_until: Optional[datetime.datetime]
+        When invites will be enabled again as a :class:`datetime.datetime`, or ``None``.
+    dms_disabled_until: Optional[datetime.datetime]
+        When direct messages will be enabled again as a :class:`datetime.datetime`, or ``None``.
+    dm_spam_detected_at: Optional[datetime.datetime]
+        When DM spam was detected, or ``None``.
+    raid_detected_at: Optional[datetime.datetime]
+        When a raid was detected, or ``None``.
+    """
+
+    __slots__ = (
+        "guild",
+        "invites_disabled_until",
+        "dms_disabled_until",
+        "dm_spam_detected_at",
+        "raid_detected_at",
+    )
+
+    def __init__(self, data: IncidentsDataPayload, guild: Optional[Guild] = None):
+        self.guild = guild
+
+        self.invites_disabled_until: datetime.datetime | None = (
+            datetime.datetime.fromisoformat(s)
+            if (s := data.get("invites_disabled_until"))
+            else None
+        )
+
+        self.dms_disabled_until: datetime.datetime | None = (
+            datetime.datetime.fromisoformat(s)
+            if (s := data.get("dms_disabled_until"))
+            else None
+        )
+
+        self.dm_spam_detected_at: datetime.datetime | None = (
+            datetime.datetime.fromisoformat(s)
+            if (s := data.get("dm_spam_detected_at"))
+            else None
+        )
+
+        self.raid_detected_at: datetime.datetime | None = (
+            datetime.datetime.fromisoformat(s)
+            if (s := data.get("raid_detected_at"))
+            else None
+        )
+
+    def to_dict(self) -> IncidentsDataPayload:
+        """Converts this object back to a raw payload suitable for API use."""
+        return {
+            "invites_disabled_until": self.invites_disabled_until
+            and self.invites_disabled_until.isoformat(),
+            "dms_disabled_until": self.dms_disabled_until
+            and self.dms_disabled_until.isoformat(),
+            "dm_spam_detected_at": self.dm_spam_detected_at
+            and self.dm_spam_detected_at.isoformat(),
+            "raid_detected_at": self.raid_detected_at
+            and self.raid_detected_at.isoformat(),
+        }

discord/types/guild.py

@@ -164,6 +164,7 @@ class Guild(_BaseGuildPreview):
     premium_tier: PremiumTier
     preferred_locale: str
     public_updates_channel_id: Snowflake | None
+    incidents_data: IncidentsData | None
 
 
 class InviteGuild(Guild, total=False):
@@ -197,3 +198,15 @@ class GuildMFAModify(TypedDict):
 class GuildBulkBan(TypedDict):
     banned_users: list[Snowflake]
     failed_users: list[Snowflake]
+
+
+class IncidentsData(TypedDict, total=False):
+    invites_disabled_until: str | None
+    dms_disabled_until: str | None
+    dm_spam_detected_at: str | None
+    raid_detected_at: str | None
+
+
+class ModifyIncidents(TypedDict, total=False):
+    invites_disabled_until: str | None
+    dms_disabled_until: str | None

pyproject.toml

@@ -105,3 +105,6 @@ max-line-length = 120
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+
+[tool.basedpyright]
+typeCheckingMode = "strict"