From d4058b83935586aba1831cfd856dfda340b2a719 Mon Sep 17 00:00:00 2001 From: Kyle Boe Date: Mon, 11 Nov 2024 20:51:51 -0800 Subject: [PATCH] Move Role API endpoints to Guild module Also updates relevant docs --- guides/intro/application_commands.md | 7 +- lib/nostrum/api.ex | 30 ++--- lib/nostrum/api/guild.ex | 155 ++++++++++++++++++++++++ lib/nostrum/api/role.ex | 170 --------------------------- 4 files changed, 173 insertions(+), 189 deletions(-) delete mode 100644 lib/nostrum/api/role.ex diff --git a/guides/intro/application_commands.md b/guides/intro/application_commands.md index 4a70c53b3..9452c8070 100644 --- a/guides/intro/application_commands.md +++ b/guides/intro/application_commands.md @@ -97,15 +97,14 @@ separate operation modes: ```elixir alias Nostrum.Api -alias Nostrum.Api.Role alias Nostrum.Struct.Interaction defp manage_role(%Interaction{data: %{options: [%{value: role_id}, %{value: "assign"}]}} = interaction) do - Role.add_member(interaction.guild_id, interaction.member.user_id, role_id) + Guild.add_member_role(interaction.guild_id, interaction.member.user_id, role_id) end defp manage_role(%Interaction{data: %{options: [%{value: role_id}, %{value: "remove"}]}} = interaction) do - Role.remove_member(interaction.guild_id, interaction.member.user_id, role_id) + Guild.remove_member_role(interaction.guild_id, interaction.member.user_id, role_id) end def handle_event({:INTERACTION_CREATE, %Interaction{data: %{name: "role"}} = interaction, _ws_state}) do @@ -123,7 +122,7 @@ To respond to interactions, use ``Nostrum.Api.Interaction.create_response/2``: ```elixir defp manage_role(%Interaction{data: %{options: [%{value: role_id}, %{value: "assign"}]}} = interaction) do - Role.add_member(interaction.guild_id, interaction.member.user_id, role_id) + Guild.add_member_role(interaction.guild_id, interaction.member.user_id, role_id) response = %{ type: 4, # ChannelMessageWithSource data: %{ diff --git a/lib/nostrum/api.ex b/lib/nostrum/api.ex index 8bd4df76d..2d1c47bce 100644 --- a/lib/nostrum/api.ex +++ b/lib/nostrum/api.ex @@ -1014,19 +1014,19 @@ defmodule Nostrum.Api do @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 - Use `Nostrum.Api.Role.add_member/4` directly instead. + Use `Nostrum.Api.Guild.add_member_role/4` directly instead. """ defdelegate add_guild_member_role(guild_id, user_id, role_id, reason \\ nil), - to: Nostrum.Api.Role, - as: :add_member + to: Nostrum.Api.Guild, + as: :add_member_role @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 - Use `Nostrum.Api.Role.remove_member/4` directly instead. + Use `Nostrum.Api.Guild.remove_member_role/4` directly instead. """ defdelegate remove_guild_member_role(guild_id, user_id, role_id, reason \\ nil), - to: Nostrum.Api.Role, - as: :remove_member + to: Nostrum.Api.Guild, + as: :remove_member_role @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 @@ -1098,11 +1098,11 @@ defmodule Nostrum.Api do @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 - Use `Nostrum.Api.Role.create/3` directly instead. + Use `Nostrum.Api.Guild.create_role/3` directly instead. """ defdelegate create_guild_role(guild_id, options, reason \\ nil), - to: Nostrum.Api.Role, - as: :create + to: Nostrum.Api.Guild, + as: :create_role @doc ~S""" Same as `create_guild_role/2`, but raises `Nostrum.Error.ApiError` in case of failure. @@ -1138,11 +1138,11 @@ defmodule Nostrum.Api do @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 - Use `Nostrum.Api.Role.modify/4` directly instead. + Use `Nostrum.Api.Guild.modify_role/4` directly instead. """ defdelegate modify_guild_role(guild_id, role_id, options, reason \\ nil), - to: Nostrum.Api.Role, - as: :modify + to: Nostrum.Api.Guild, + as: :modify_role @doc ~S""" Same as `modify_guild_role/3`, but raises `Nostrum.Error.ApiError` in case of failure. @@ -1157,11 +1157,11 @@ defmodule Nostrum.Api do @deprecated """ Calling `Nostrum.Api` functions directly will be removed in v1.0 - Use `Nostrum.Api.Role.delete/3` directly instead. + Use `Nostrum.Api.Guild.delete_role/3` directly instead. """ defdelegate delete_guild_role(guild_id, role_id, reason \\ nil), - to: Nostrum.Api.Role, - as: :delete + to: Nostrum.Api.Guild, + as: :delete_role @doc ~S""" Same as `delete_guild_role/2`, but raises `Nostrum.Error.ApiError` in case of failure. diff --git a/lib/nostrum/api/guild.ex b/lib/nostrum/api/guild.ex index 1f72dfe1b..f6477a5a3 100644 --- a/lib/nostrum/api/guild.ex +++ b/lib/nostrum/api/guild.ex @@ -69,6 +69,25 @@ defmodule Nostrum.Api.Guild do |> Helpers.handle_request_with_decode({:struct, Member}) end + @doc """ + Adds a role to a member. + + Role to add is specified by `role_id`. + User to add role to is specified by `guild_id` and `user_id`. + An optional `reason` can be given for the audit log. + """ + @spec add_member_role(Guild.id(), User.id(), Role.id(), AuditLogEntry.reason()) :: + Api.error() | {:ok} + def add_member_role(guild_id, user_id, role_id, reason \\ nil) do + Api.request(%{ + method: :put, + route: Constants.guild_member_role(guild_id, user_id, role_id), + body: "", + params: [], + headers: Helpers.maybe_add_reason(reason) + }) + end + @doc """ Begins a guild prune to prune members within `days`. @@ -182,6 +201,51 @@ defmodule Nostrum.Api.Guild do Api.request(:post, Constants.guild_integrations(guild_id), options) end + @doc ~S""" + Creates a guild role. + + An optional reason for the audit log can be provided via `reason`. + + This endpoint requires the `MANAGE_ROLES` permission. It fires a + `t:Nostrum.Consumer.guild_role_create/0` event. + + If successful, returns `{:ok, role}`. Otherwise, returns a `t:Nostrum.Api.error/0`. + + ## Options + + * `:name` (string) - name of the role (default: "new role") + * `:permissions` (integer) - bitwise of the enabled/disabled permissions (default: @everyone perms) + * `:color` (integer) - RGB color value (default: 0) + * `:hoist` (boolean) - whether the role should be displayed separately in the sidebar (default: false) + * `:mentionable` (boolean) - whether the role should be mentionable (default: false) + * `:icon` (string) - URL role icon (default: `nil`) + * `:unicode_emoji` (string) - standard unicode character emoji role icon (default: `nil`) + + ## Examples + + ```elixir + Nostrum.Api.Guild.create_role(41771983423143937, name: "nostrum-club", hoist: true) + ``` + """ + @spec create_role(Guild.id(), Api.options(), AuditLogEntry.reason()) :: + Api.error() | {:ok, Role.t()} + def create_role(guild_id, options, reason \\ nil) + + def create_role(guild_id, options, reason) when is_list(options), + do: create_role(guild_id, Map.new(options), reason) + + def create_role(guild_id, %{} = options, reason) when is_snowflake(guild_id) do + %{ + method: :post, + route: Constants.guild_roles(guild_id), + body: options, + params: [], + headers: Helpers.maybe_add_reason(reason) + } + |> Api.request() + |> Helpers.handle_request_with_decode({:struct, Role}) + end + @doc ~S""" Deletes a guild. @@ -234,6 +298,34 @@ defmodule Nostrum.Api.Guild do Api.request(:delete, Constants.guild_integration(guild_id, integration_id)) end + @doc ~S""" + Deletes a role from a guild. + + An optional `reason` can be specified for the audit log. + + This endpoint requires the `MANAGE_ROLES` permission. It fires a + `t:Nostrum.Consumer.guild_role_delete/0` event. + + If successful, returns `{:ok}`. Otherwise, returns a `t:Nostrum.Api.error/0`. + + ## Examples + + ```elixir + Nostrum.Api.Guild.delete_role(41771983423143937, 392817238471936) + ``` + """ + @spec delete_role(Guild.id(), Role.id(), AuditLogEntry.reason()) :: Api.error() | {:ok} + def delete_role(guild_id, role_id, reason \\ nil) + when is_snowflake(guild_id) and is_snowflake(role_id) do + Api.request(%{ + method: :delete, + route: Constants.guild_role(guild_id, role_id), + body: "", + params: [], + headers: Helpers.maybe_add_reason(reason) + }) + end + @doc ~S""" Gets a guild. @@ -369,6 +461,69 @@ defmodule Nostrum.Api.Guild do |> Helpers.handle_request_with_decode() end + @doc ~S""" + Modifies a guild role. + + This endpoint requires the `MANAGE_ROLES` permission. It fires a + `t:Nostrum.Consumer.guild_role_update/0` event. + + An optional `reason` can be specified for the audit log. + + If successful, returns `{:ok, role}`. Otherwise, returns a `t:Nostrum.Api.error/0`. + + ## Options + + * `:name` (string) - name of the role + * `:permissions` (integer) - bitwise of the enabled/disabled permissions + * `:color` (integer) - RGB color value (default: 0) + * `:hoist` (boolean) - whether the role should be displayed separately in the sidebar + * `:mentionable` (boolean) - whether the role should be mentionable + + ## Examples + + ```elixir + Nostrum.Api.Guild.modify_role(41771983423143937, 392817238471936, hoist: false, name: "foo-bar") + ``` + """ + @spec modify_role(Guild.id(), Role.id(), Api.options(), AuditLogEntry.reason()) :: + Api.error() | {:ok, Role.t()} + def modify_role(guild_id, role_id, options, reason \\ nil) + + def modify_role(guild_id, role_id, options, reason) when is_list(options), + do: modify_role(guild_id, role_id, Map.new(options), reason) + + def modify_role(guild_id, role_id, %{} = options, reason) + when is_snowflake(guild_id) and is_snowflake(role_id) do + %{ + method: :patch, + route: Constants.guild_role(guild_id, role_id), + body: options, + params: [], + headers: Helpers.maybe_add_reason(reason) + } + |> Api.request() + |> Helpers.handle_request_with_decode({:struct, Role}) + end + + @doc """ + Removes a role from a member. + + Role to remove is specified by `role_id`. + User to remove role from is specified by `guild_id` and `user_id`. + An optional `reason` can be given for the audit log. + """ + @spec remove_member_role(Guild.id(), User.id(), Role.id(), AuditLogEntry.reason()) :: + Api.error() | {:ok} + def remove_member_role(guild_id, user_id, role_id, reason \\ nil) do + Api.request(%{ + method: :delete, + route: Constants.guild_member_role(guild_id, user_id, role_id), + body: "", + params: [], + headers: Helpers.maybe_add_reason(reason) + }) + end + @doc ~S""" Gets a guild's roles. diff --git a/lib/nostrum/api/role.ex b/lib/nostrum/api/role.ex deleted file mode 100644 index fb93f78f6..000000000 --- a/lib/nostrum/api/role.ex +++ /dev/null @@ -1,170 +0,0 @@ -defmodule Nostrum.Api.Role do - @moduledoc """ - Module for interacting with the Discord API's role endpoints. - - See: https://discord.com/developers/docs/resources/guild#get-guild-roles - """ - alias Nostrum.Api - alias Nostrum.Api.Helpers - alias Nostrum.Constants - alias Nostrum.Struct.Guild - alias Nostrum.Struct.Guild.AuditLogEntry - alias Nostrum.Struct.Guild.Role - alias Nostrum.Struct.User - - import Nostrum.Snowflake, only: [is_snowflake: 1] - - @doc """ - Adds a role to a member. - - Role to add is specified by `role_id`. - User to add role to is specified by `guild_id` and `user_id`. - An optional `reason` can be given for the audit log. - """ - @spec add_member(Guild.id(), User.id(), Role.id(), AuditLogEntry.reason()) :: - Api.error() | {:ok} - def add_member(guild_id, user_id, role_id, reason \\ nil) do - Api.request(%{ - method: :put, - route: Constants.guild_member_role(guild_id, user_id, role_id), - body: "", - params: [], - headers: Helpers.maybe_add_reason(reason) - }) - end - - @doc ~S""" - Creates a guild role. - - An optional reason for the audit log can be provided via `reason`. - - This endpoint requires the `MANAGE_ROLES` permission. It fires a - `t:Nostrum.Consumer.guild_role_create/0` event. - - If successful, returns `{:ok, role}`. Otherwise, returns a `t:Nostrum.Api.error/0`. - - ## Options - - * `:name` (string) - name of the role (default: "new role") - * `:permissions` (integer) - bitwise of the enabled/disabled permissions (default: @everyone perms) - * `:color` (integer) - RGB color value (default: 0) - * `:hoist` (boolean) - whether the role should be displayed separately in the sidebar (default: false) - * `:mentionable` (boolean) - whether the role should be mentionable (default: false) - * `:icon` (string) - URL role icon (default: `nil`) - * `:unicode_emoji` (string) - standard unicode character emoji role icon (default: `nil`) - - ## Examples - - ```elixir - Nostrum.Api.Role.create(41771983423143937, name: "nostrum-club", hoist: true) - ``` - """ - @spec create(Guild.id(), Api.options(), AuditLogEntry.reason()) :: Api.error() | {:ok, Role.t()} - def create(guild_id, options, reason \\ nil) - - def create(guild_id, options, reason) when is_list(options), - do: create(guild_id, Map.new(options), reason) - - def create(guild_id, %{} = options, reason) when is_snowflake(guild_id) do - %{ - method: :post, - route: Constants.guild_roles(guild_id), - body: options, - params: [], - headers: Helpers.maybe_add_reason(reason) - } - |> Api.request() - |> Helpers.handle_request_with_decode({:struct, Role}) - end - - @doc ~S""" - Deletes a role from a guild. - - An optional `reason` can be specified for the audit log. - - This endpoint requires the `MANAGE_ROLES` permission. It fires a - `t:Nostrum.Consumer.guild_role_delete/0` event. - - If successful, returns `{:ok}`. Otherwise, returns a `t:Nostrum.Api.error/0`. - - ## Examples - - ```elixir - Nostrum.Api.Role.delete(41771983423143937, 392817238471936) - ``` - """ - @spec delete(Guild.id(), Role.id(), AuditLogEntry.reason()) :: Api.error() | {:ok} - def delete(guild_id, role_id, reason \\ nil) - when is_snowflake(guild_id) and is_snowflake(role_id) do - Api.request(%{ - method: :delete, - route: Constants.guild_role(guild_id, role_id), - body: "", - params: [], - headers: Helpers.maybe_add_reason(reason) - }) - end - - @doc ~S""" - Modifies a guild role. - - This endpoint requires the `MANAGE_ROLES` permission. It fires a - `t:Nostrum.Consumer.guild_role_update/0` event. - - An optional `reason` can be specified for the audit log. - - If successful, returns `{:ok, role}`. Otherwise, returns a `t:Nostrum.Api.error/0`. - - ## Options - - * `:name` (string) - name of the role - * `:permissions` (integer) - bitwise of the enabled/disabled permissions - * `:color` (integer) - RGB color value (default: 0) - * `:hoist` (boolean) - whether the role should be displayed separately in the sidebar - * `:mentionable` (boolean) - whether the role should be mentionable - - ## Examples - - ```elixir - Nostrum.Api.Role.modify(41771983423143937, 392817238471936, hoist: false, name: "foo-bar") - ``` - """ - @spec modify(Guild.id(), Role.id(), Api.options(), AuditLogEntry.reason()) :: - Api.error() | {:ok, Role.t()} - def modify(guild_id, role_id, options, reason \\ nil) - - def modify(guild_id, role_id, options, reason) when is_list(options), - do: modify(guild_id, role_id, Map.new(options), reason) - - def modify(guild_id, role_id, %{} = options, reason) - when is_snowflake(guild_id) and is_snowflake(role_id) do - %{ - method: :patch, - route: Constants.guild_role(guild_id, role_id), - body: options, - params: [], - headers: Helpers.maybe_add_reason(reason) - } - |> Api.request() - |> Helpers.handle_request_with_decode({:struct, Role}) - end - - @doc """ - Removes a role from a member. - - Role to remove is specified by `role_id`. - User to remove role from is specified by `guild_id` and `user_id`. - An optional `reason` can be given for the audit log. - """ - @spec remove_member(Guild.id(), User.id(), Role.id(), AuditLogEntry.reason()) :: - Api.error() | {:ok} - def remove_member(guild_id, user_id, role_id, reason \\ nil) do - Api.request(%{ - method: :delete, - route: Constants.guild_member_role(guild_id, user_id, role_id), - body: "", - params: [], - headers: Helpers.maybe_add_reason(reason) - }) - end -end