Move Role API endpoints to Guild module

Also updates relevant docs

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: %{

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.

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.