[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