[Feature] Expose `GetCurrentUser` method & missing current user API methods (#2574)

* add stuff

* forgot to push

* docs

* Update DiscordRestClient.cs

* Apply suggestions from code review

* Update toc.yml

---------

Co-authored-by: Casmir <68127614+csmir@users.noreply.github.com>

docs/guides/bearer_token/bearer_token_guide.md

@@ -0,0 +1,68 @@
+---
+uid: Guides.BearerToken
+title: Working with Bearer token
+---
+
+# Working with Bearer token
+
+Some endpoints in Discord API require a Bearer token, which can be obtained through [OAuth2 flow](https://discord.com/developers/docs/topics/oauth2). Discord.Net allows you to interact with these endpoints using the [DiscordRestClient].
+
+## Initializing a new instance of the client
+[!code-csharp[Initialize DiscordRestClient](samples/rest_client_init.cs)]
+
+## Getting current user
+
+The [DiscordRestClient] gets the current user when `LoginAsync()` is called. The user object can be found in the `CurrentUser` property.
+
+If you need to fetch the user again, the `GetGetCurrentUserAsync()` method can be used.
+
+[!code-csharp[Get current user](samples/current_user.cs)]
+
+> [!NOTE]
+> Some properties might be `null` depending on which scopes users authorized your app with.
+> For example: `email` scope is required to fetch current user's email address.
+
+## Fetching current user's guilds
+
+The `GetGuildSummariesAsync()` method is used to fetch current user's guilds. Since it returns an `IAsyncEnumerable` you need to call `FlattenAsync()` to get a plain `IEnumerable` containing [RestUserGuild] objects.
+
+[!code-csharp[Get current user's guilds](samples/current_user_guilds.cs)]
+
+> [!WARNING]
+> This method requires `guilds` scope
+
+## Fetching current user's guild member object
+
+To fetch the current user's guild member object, the `GetCurrentUserGuildMemberAsync()` method can be used. 
+
+[!code-csharp[Get current user's guild member](samples/current_user_guild_member.cs)]
+
+> [!WARNING]
+> This method requires `guilds.members.read` scope
+
+## Get user connections
+
+The `GetConnectionsAsync` method can be used to fetch current user's connections to other platforms.
+
+[!code-csharp[Get current user's connections](samples/current_user_connections.cs)]
+
+> [!WARNING]
+> This method requires `connections` scope
+
+## Application role connection
+
+In addition to previous features, Discord.Net supports fetching & updating user's application role connection metadata values. `GetUserApplicationRoleConnectionAsync()` returns a [RoleConnection] object of the current user for the given application id.
+
+The `ModifyUserApplicationRoleConnectionAsync()` method is used to update current user's role connection metadata values. A new set of values can be created with [RoleConnectionProperties] object.
+
+[!code-csharp[Get current user's connections](samples/app_role_connection.cs)]
+
+> [!WARNING]
+> This method requires `role_connections.write` scope
+
+
+
+[DiscordRestClient]: xref:Discord.Rest.DiscordRestClient
+[RestUserGuild]: xref:Discord.Rest.RestUserGuild
+[RoleConnection]: xref:Discord.RoleConnection
+[RoleConnectionProperties]: xref:Discord.RoleConnectionProperties

docs/guides/bearer_token/samples/app_role_connection.cs

@@ -0,0 +1,11 @@
+// fetch application role connection of the current user for the app with provided id.
+var roleConnection = await client.GetUserApplicationRoleConnectionAsync(applicationid);
+
+// create a new role connection metadata properties object & set some values.
+var properties = new RoleConnectionProperties("Discord.Net Docs", "Cool Coding Guy")
+    .WithNumber("eaten_cookies", 69)
+    .WithBool("loves_cookies", true)
+    .WithDate("last_eaten_cookie", DateTimeOffset.UtcNow);
+
+// update current user's values with the given properties.
+await client.ModifyUserApplicationRoleConnectionAsync(applicationId, properties);

docs/guides/bearer_token/samples/current_user.cs

@@ -0,0 +1,5 @@
+// gets the user object stored in the DiscordRestClient.
+var user = client.CurrentUser;
+
+// fetches the current user with a REST call & updates the CurrentUser property.
+var refreshedUser = await client.GetCurrentUserAsync();

docs/guides/bearer_token/samples/current_user_connections.cs

@@ -0,0 +1,2 @@
+// fetches the current user's connections.
+var connections = await client.GetConnectionsAsync();

docs/guides/bearer_token/samples/current_user_guild_member.cs

@@ -0,0 +1,6 @@
+// fetches the current user's guild member object in a guild with provided id.
+var member = await client.GetCurrentUserGuildMemberAsync(guildId);
+
+// fetches the current user's guild member object in a RestUserGuild.
+var guild = await client.GetGuildSummariesAsync().FlattenAsync().First();
+var member = await guild.GetCurrentUserGuildMemberAsync();

docs/guides/bearer_token/samples/current_user_guilds.cs

@@ -0,0 +1,2 @@
+// fetches the guilds the current user participate in.
+var guilds = await client.GetGuildSummariesAsync().FlattenAsync();

docs/guides/bearer_token/samples/rest_client_init.cs

@@ -0,0 +1,5 @@
+using Discord;
+using Discord.Rest;
+
+await using var client = new DiscordRestClient();
+await client.LoginAsync(TokenType.Bearer, "bearer token obtained through oauth2 flow");

docs/guides/toc.yml

@@ -126,6 +126,8 @@
       topicUid: Guides.OtherLibs.MediatR
 - name: Emoji
   topicUid: Guides.Emoji
+- name: Bearer Tokens
+  topicUid: Guides.BearerToken
 - name: Voice
   topicUid: Guides.Voice.SendingVoice
 - name: Deployment

src/Discord.Net.Core/Entities/Guilds/IUserGuild.cs

@@ -18,5 +18,13 @@ namespace Discord
         ///     Returns the current user's permissions for this guild.
         /// </summary>
         GuildPermissions Permissions { get; }
+
+        /// <summary>
+        ///     Gets the features for this guild.
+        /// </summary>
+        /// <returns>
+        ///     A flags enum containing all the features for the guild.
+        /// </returns>
+        GuildFeatures Features { get; }
     }
 }

src/Discord.Net.Rest/API/Common/UserGuild.cs

@@ -14,5 +14,7 @@ namespace Discord.API
         public bool Owner { get; set; }
         [JsonProperty("permissions"), Int53]
         public string Permissions { get; set; }
+        [JsonProperty("features")]
+        public GuildFeatures Features { get; set; }
     }
 }

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -1,4 +1,3 @@
-
 using Discord.API.Rest;
 using Discord.Net;
 using Discord.Net.Converters;
@@ -2204,6 +2203,14 @@ namespace Discord.API
 
             return await SendJsonAsync<Channel>("POST", () => "users/@me/channels", args, new BucketIds(), options: options).ConfigureAwait(false);
         }
+
+        public async Task<GuildMember> GetCurrentUserGuildMember(ulong guildId, RequestOptions options = null)
+        {
+            options = RequestOptions.CreateOrClone(options);
+
+            var ids = new BucketIds();
+            return await SendAsync<GuildMember>("GET", () => $"users/@me/guilds/{guildId}/member", ids, options: options).ConfigureAwait(false);
+        }
         #endregion
 
         #region Voice Regions

src/Discord.Net.Rest/DiscordRestClient.cs

@@ -152,6 +152,19 @@ namespace Discord.Rest
 
         #endregion
         
+        public async Task<RestSelfUser> GetCurrentUserAsync(RequestOptions options = null)
+        {
+            var user = await ApiClient.GetMyUserAsync(options);
+            CurrentUser.Update(user);
+            return CurrentUser;
+        }
+
+        public async Task<RestGuildUser> GetCurrentUserGuildMemberAsync(ulong guildId, RequestOptions options = null)
+        {
+            var user = await ApiClient.GetCurrentUserGuildMember(guildId, options);
+            return RestGuildUser.Create(this, null, user, guildId);
+        }
+
         public async Task<RestApplication> GetApplicationInfoAsync(RequestOptions options = null)
         {
             return _applicationInfo ??= await ClientHelper.GetApplicationInfoAsync(this, options).ConfigureAwait(false);

src/Discord.Net.Rest/Entities/Guilds/RestUserGuild.cs

@@ -21,6 +21,8 @@ namespace Discord.Rest
         public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id);
         /// <inheritdoc />
         public string IconUrl => CDN.GetGuildIconUrl(Id, _iconId);
+        /// <inheritdoc />
+        public GuildFeatures Features { get; private set; }
 
         internal RestUserGuild(BaseDiscordClient discord, ulong id)
             : base(discord, id)
@@ -39,12 +41,20 @@ namespace Discord.Rest
             IsOwner = model.Owner;
             Name = model.Name;
             Permissions = new GuildPermissions(model.Permissions);
+            Features = model.Features;
         }
         
         public async Task LeaveAsync(RequestOptions options = null)
         {
             await Discord.ApiClient.LeaveGuildAsync(Id, options).ConfigureAwait(false);
         }
+
+        public async Task<RestGuildUser> GetCurrentUserGuildMemberAsync(RequestOptions options = null)
+        {
+            var user = await Discord.ApiClient.GetCurrentUserGuildMember(Id, options);
+            return RestGuildUser.Create(Discord, null, user, Id);
+        }
+
         /// <inheritdoc />
         public async Task DeleteAsync(RequestOptions options = null)
         {