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_guild_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.UndefinedNoneOr[
+ typing.Sequence[snowflakes.SnowflakeishOr[channels_.GuildChannel]]
+ ] = undefined.UNDEFINED,
+ mode: undefined.UndefinedOr[guilds.OnboardingMode] = undefined.UNDEFINED,
+ prompts: undefined.UndefinedNoneOr[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/guilds.py

@@ -1302,6 +1302,97 @@ 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(unsafe_hash=False, 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.List[OnboardingPrompt] = attrs.field(repr=True)
+ """Prompts shown during onboarding and in customize community."""
+
+ default_channel_ids: typing.List[snowflakes.Snowflake] = attrs.field(repr=True)
+ """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(unsafe_hash=False, 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=True)
+ """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=True)
+ """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)
+
+ channel_ids: typing.Sequence[snowflakes.Snowflake] = attrs.field(repr=True)
+
+ role_ids: typing.Sequence[snowflakes.Snowflake] = attrs.field(repr=True)
+
+ emoji: typing.Optional[emojis_.Emoji] = attrs.field(repr=True)
+
+ title: str = attrs.field(repr=True)
+
+ description: typing.Optional[str] = attrs.field(repr=True)
+
+
 @attrs_extensions.with_copy
 @attrs.define(kw_only=True, weakref_slot=False)
 class WelcomeScreen:

hikari/impl/entity_factory.py

@@ -1776,6 +1776,101 @@ def deserialize_guild_widget(self, payload: data_binding.JSONObject) -> guild_mo
 
  return guild_models.GuildWidget(app=self._app, channel_id=channel_id, is_enabled=payload["enabled"])
 
+ def deserialize_guild_onboarding(self, payload: data_binding.JSONObject) -> guild_models.GuildOnboarding:
+ default_channel_ids: typing.List[snowflakes.Snowflake] = []
+ for raw_channel_id in payload["default_channel_ids"]:
+ default_channel_ids.append(snowflakes.Snowflake(raw_channel_id))
+
+ prompts: typing.List[guild_models.OnboardingPrompt] = []
+ for prompt_payload in payload["prompts"]:
+ prompts.append(self.deserialize_onboarding_prompt(prompt_payload))
+
+ mode: guild_models.OnboardingMode = guild_models.OnboardingMode(payload["mode"])
+
+ return guild_models.GuildOnboarding(
+ guild_id=snowflakes.Snowflake(payload["guild_id"]),
+ prompts=prompts,
+ default_channel_ids=default_channel_ids,
+ mode=mode,
+ enabled=bool(payload.get("enabled")),
+ )
+
+ def deserialize_onboarding_prompt(self, payload: data_binding.JSONObject) -> guild_models.OnboardingPrompt:
+ options: typing.List[guild_models.OnboardingPromptOption] = []
+ for option_payload in payload["options"]:
+ options.append(self.deserialize_onboarding_prompt_option(option_payload))
+
+ return guild_models.OnboardingPrompt(
+ id=snowflakes.Snowflake(payload["id"]),
+ type=guild_models.OnboardingPromptType(payload["type"]),
+ options=options,
+ title=payload["title"],
+ single_select=bool(payload.get("single_select")),
+ required=bool(payload.get("required")),
+ in_onboarding=bool(payload.get("in_onboarding")),
+ )
+
+ def deserialize_onboarding_prompt_option(
+ self, payload: data_binding.JSONObject
+ ) -> guild_models.OnboardingPromptOption:
+ channel_ids: typing.List[snowflakes.Snowflake] = []
+ for raw_channel_id in payload["channel_ids"]:
+ channel_ids.append(snowflakes.Snowflake(raw_channel_id))
+
+ role_ids: typing.List[snowflakes.Snowflake] = []
+ for raw_role_id in payload["role_ids"]:
+ role_ids.append(snowflakes.Snowflake(raw_role_id))
+
+ description = payload.get("description", None)
+
+ emoji: typing.Optional[emoji_models.Emoji] = None
+ if raw_emoji := payload.get("emoji"):
+ emoji = self.deserialize_emoji(raw_emoji)
+
+ return guild_models.OnboardingPromptOption(
+ id=snowflakes.Snowflake(payload["id"]),
+ channel_ids=channel_ids,
+ role_ids=role_ids,
+ emoji=emoji,
+ title=payload["title"],
+ description=description,
+ )
+
+ def serialize_onboarding_prompt(self, prompt: guild_models.OnboardingPrompt) -> data_binding.JSONObject:
+ payload: typing.Dict[str, typing.Any] = {
+ "id": str(prompt.id),
+ "type": prompt.type.value,
+ "title": prompt.title,
+ "options": [self.serialize_onboarding_prompt_option(option) for option in prompt.options],
+ "single_select": prompt.single_select,
+ "required": prompt.required,
+ "in_onboarding": prompt.in_onboarding,
+ }
+
+ return payload
+
+ def serialize_onboarding_prompt_option(
+ self, option: guild_models.OnboardingPromptOption
+ ) -> data_binding.JSONObject:
+ payload: typing.Dict[str, typing.Any] = {
+ "id": str(option.id),
+ "channel_ids": [str(channel_id) for channel_id in option.channel_ids],
+ "role_ids": [str(role_id) for role_id in option.role_ids],
+ "title": option.title,
+ }
+
+ if option.description is not None:
+ payload["description"] = option.description
+
+ if isinstance(option.emoji, emoji_models.UnicodeEmoji):
+ payload["emoji_name"] = option.emoji.name
+ elif isinstance(option.emoji, emoji_models.CustomEmoji):
+ payload["emoji_id"] = str(option.emoji.id)
+ payload["emoji_name"] = option.emoji.name
+ payload["emoji_animated"] = option.emoji.is_animated
+
+ return payload
+
  def deserialize_welcome_screen(self, payload: data_binding.JSONObject) -> guild_models.WelcomeScreen:
  channels: typing.List[guild_models.WelcomeChannel] = []