Feature/add guild onboarding

changes/2005.feature.md

@@ -0,0 +1 @@
+Add guild onboarding functionality

hikari/api/entity_factory.py

@@ -1014,6 +1014,85 @@ def deserialize_guild_widget(self, payload: data_binding.JSONObject) -> guild_mo
             The deserialized guild widget object.
         """
 
+    @abc.abstractmethod
+    def deserialize_onboarding(self, payload: data_binding.JSONObject) -> guild_models.GuildOnboarding:
+        """Parse a raw payload from Discord into a guild onboarding object.
+
+        Parameters
+        ----------
+        payload
+            The JSON payload to deserialize.
+
+        Returns
+        -------
+        hikari.guilds.GuildOnboarding
+            The deserialized guild onboarding object.
+        """
+
+    @abc.abstractmethod
+    def deserialize_onboarding_prompt(self, payload: data_binding.JSONObject) -> guild_models.OnboardingPrompt:
+        """Parse a raw payload from Discord into an onboarding prompt object.
+
+        Parameters
+        ----------
+        payload
+            The JSON payload to deserialize.
+
+        Returns
+        -------
+        hikari.guilds.OnboardingPrompt
+            The deserialized onboarding prompt object.
+        """
+
+    @abc.abstractmethod
+    def deserialize_onboarding_prompt_option(
+        self, payload: data_binding.JSONObject
+    ) -> guild_models.OnboardingPromptOption:
+        """Parse a raw payload from Discord into an onboarding prompt option object.
+
+        Parameters
+        ----------
+        payload
+            The JSON payload to deserialize.
+
+        Returns
+        -------
+        hikari.guilds.OnboardingPromptOption
+            The deserialized onboarding prompt option object.
+        """
+
+    @abc.abstractmethod
+    def serialize_onboarding_prompt_option(
+        self, option: guild_models.OnboardingPromptOption
+    ) -> data_binding.JSONObject:
+        """Serialize an onboarding prompt option object to a json serializable dict.
+
+        Parameters
+        ----------
+        option
+            The onboarding prompt option object to serialize.
+
+        Returns
+        -------
+        hikari.internal.data_binding.JSONObject
+            The serialized representation of the onboarding prompt option.
+        """
+
+    @abc.abstractmethod
+    def serialize_onboarding_prompt(self, prompt: guild_models.OnboardingPrompt) -> data_binding.JSONObject:
+        """Serialize an onboarding prompt object to a json serializable dict.
+
+        Parameters
+        ----------
+        prompt
+            The onboarding prompt object to serialize.
+
+        Returns
+        -------
+        hikari.internal.data_binding.JSONObject
+            The serialized representation of the onboarding prompt.
+        """
+
     @abc.abstractmethod
     def deserialize_welcome_screen(self, payload: data_binding.JSONObject) -> guild_models.WelcomeScreen:
         """Parse a raw payload from Discord into a guild welcome screen object.

hikari/api/rest.py

@@ -6452,6 +6452,89 @@ async def edit_welcome_screen(
             If an internal error occurs on Discord while handling the request.
         """
 
+    @abc.abstractmethod
+    async def fetch_guild_onboarding(
+        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild]
+    ) -> guilds.GuildOnboarding:
+        """Fetch a guild's onboarding.
+
+        Parameters
+        ----------
+        guild
+            Object or ID of the guild to fetch the welcome screen for.
+
+        Returns
+        -------
+        hikari.guilds.GuildOnboarding
+            The requested onboarding object.
+
+        Raises
+        ------
+        hikari.errors.NotFoundError
+            If the guild is not found or the welcome screen has never been set
+            for this guild (if the welcome screen has been set for a guild
+            before and then disabled you should still be able to fetch it).
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """
+
+    @abc.abstractmethod
+    async def edit_guild_onboarding(
+        self,
+        guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
+        *,
+        enabled: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+        default_channels: undefined.UndefinedOr[
+            typing.Sequence[snowflakes.SnowflakeishOr[channels_.GuildChannel]]
+        ] = undefined.UNDEFINED,
+        mode: undefined.UndefinedOr[guilds.OnboardingMode] = undefined.UNDEFINED,
+        prompts: undefined.UndefinedOr[typing.Sequence[guilds.OnboardingPrompt]] = undefined.UNDEFINED,
+        reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+    ) -> guilds.GuildOnboarding:
+        """Edit the onboarding of a community guild.
+
+        Parameters
+        ----------
+        guild
+            ID or object of the guild to edit the onboarding for.
+        enabled
+            If provided, Whether the guild's onboarding should be enabled.
+        default_channels
+            If provided, channel IDs that members get opted into automatically.
+        mode
+            If provided, the onboarding mode to set for the guild.
+        prompts
+            If provided, prompts shown during onboarding and in customize community.
+
+        Returns
+        -------
+        hikari.guilds.GuildOnboarding
+            The edited onboarding object.
+
+        Raises
+        ------
+        hikari.errors.BadRequestError
+            # TODO: fix docs
+        hikari.errors.ForbiddenError
+            If you are missing the [`hikari.permissions.Permissions.MANAGE_GUILD`][] permission, are not part of
+            the guild or the guild doesn't have access to the community welcome
+            screen feature.
+        hikari.errors.NotFoundError
+            If the guild is not found.
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """
+
     @abc.abstractmethod
     async def fetch_vanity_url(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild]) -> invites.VanityURL:
         """Fetch a guild's vanity url.

hikari/audit_logs.py

@@ -265,6 +265,27 @@ class AuditLogChangeKey(str, enums.Enum):
     COMMUNICATION_DISABLED_UNTIL = "communication_disabled_until"
     """The datetime when a timeout will expire."""
 
+    ENABLED = "enabled"
+    """Enabled."""
+
+    DEFAULT_CHANNEL_IDS = "default_channel_ids"
+    """Default Channel IDs."""
+
+    MODE = "mode"
+    """Mode."""
+
+    PROMPTS = "prompts"
+    """Prompts."""
+
+    OPTIONS = "options"
+    """Options."""
+
+    SINGLE_SELECT = "single_select"
+    """Single Select."""
+
+    REQUIRED = "required"
+    """Required."""
+
     # Who needs consistency?
     ADD_ROLE_TO_MEMBER = "$add"
     """Role added to a member."""
@@ -345,6 +366,11 @@ class AuditLogEventType(int, enums.Enum):
     THREAD_DELETE = 112
     CREATOR_MONETIZATION_REQUEST_CREATED = 150
     CREATOR_MONETIZATION_TERMS_ACCEPTED = 151
+    ONBOARDING_PROMPT_CREATE = 163
+    ONBOARDING_PROMPT_UPDATE = 164
+    ONBOARDING_PROMPT_DELETE = 165
+    ONBOARDING_CREATE = 166
+    ONBOARDING_UPDATE = 167
 
 
 @attrs.define(kw_only=True, weakref_slot=False)

hikari/guilds.py

@@ -1302,6 +1302,103 @@ class WelcomeChannel:
     """ID of the emoji shown in the welcome screen channel if it's set to a custom emoji."""
 
 
+@typing.final
+class OnboardingPromptType(int, enums.Enum):
+    """The type of onboarding prompt."""
+
+    MULTIPLE_CHOICE = 0
+    """A multiple choice prompt."""
+
+    DROPDOWN = 1
+    """A dropdown prompt."""
+
+
+@typing.final
+class OnboardingMode(int, enums.Enum):
+    """The mode of onboarding."""
+
+    ONBOARDING_DEFAULT = 0
+    """Counts only Default Channels towards constraints."""
+
+    ONBOARDING_ADVANCED = 1
+    """Counts Default Channels and Questions towards constraints."""
+
+
+@attrs_extensions.with_copy
+@attrs.define(kw_only=True, weakref_slot=False)
+class GuildOnboarding:
+    """Used to represent guild onboarding settings on Discord."""
+
+    guild_id: snowflakes.Snowflake = attrs.field(repr=True)
+    """ID of the guild this onboarding is part of."""
+
+    prompts: typing.Sequence[OnboardingPrompt] = attrs.field(repr=False)
+    """Prompts shown during onboarding and in customize community."""
+
+    default_channel_ids: typing.Sequence[snowflakes.Snowflake] = attrs.field(repr=False)
+    """Channel IDs that members get opted into automatically."""
+
+    enabled: bool = attrs.field(repr=True)
+    """Whether the guild onboarding is enabled."""
+
+    mode: OnboardingMode = attrs.field(repr=True)
+    """The mode of onboarding."""
+
+
+@attrs_extensions.with_copy
+@attrs.define(kw_only=True, weakref_slot=False)
+class OnboardingPrompt:
+    """Used to represent an onboarding prompt."""
+
+    id: snowflakes.Snowflake = attrs.field(repr=True)
+    """The ID of the onboarding prompt."""
+
+    type: OnboardingPromptType = attrs.field(repr=True)
+    """The type of the onboarding prompt."""
+
+    options: typing.List[OnboardingPromptOption] = attrs.field(repr=False)
+    """Options available within the prompt."""
+
+    title: str = attrs.field(repr=True)
+    """The title of the onboarding prompt."""
+
+    single_select: bool = attrs.field(repr=True)
+    """Indicates whether users are limited to selecting one option for the prompt."""
+
+    required: bool = attrs.field(repr=True)
+    """Indicates whether the prompt is required before a user completes the onboarding flow."""
+
+    in_onboarding: bool = attrs.field(repr=False)
+    """Indicates whether the prompt is present in the onboarding flow.
+
+    If `[False][]`, the prompt will only appear in the "Channels & Roles" tab.
+    """
+
+
+@attrs_extensions.with_copy
+@attrs.define(unsafe_hash=False, kw_only=True, weakref_slot=False)
+class OnboardingPromptOption:
+    """Used to represent an onboarding prompt option."""
+
+    id: snowflakes.Snowflake = attrs.field(repr=True)
+    """ID of the prompt option."""
+
+    channel_ids: typing.Sequence[snowflakes.Snowflake] = attrs.field(repr=False)
+    """IDs for channels a member is added to when the option is selected."""
+
+    role_ids: typing.Sequence[snowflakes.Snowflake] = attrs.field(repr=False)
+    """IDs for roles assigned to a member when the option is selected."""
+
+    emoji: typing.Optional[emojis_.Emoji] = attrs.field(repr=True)
+    """Emoji of the option."""
+
+    title: str = attrs.field(repr=True)
+    """Title of the option."""
+
+    description: typing.Optional[str] = attrs.field(repr=True)
+    """Description of the option."""
+
+
 @attrs_extensions.with_copy
 @attrs.define(kw_only=True, weakref_slot=False)
 class WelcomeScreen: