Merge branch 'dev' of https://github.com/discord-net/Discord.Net into…

… dev

Discord.Net.sln

@@ -40,7 +40,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Analyzers.Tests
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Examples", "src\Discord.Net.Examples\Discord.Net.Examples.csproj", "{47820065-3CFB-401C-ACEA-862BD564A404}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "idn", "samples\idn\idn.csproj", "{4A03840B-9EBE-47E3-89AB-E0914DF21AFB}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "idn", "samples\idn\idn.csproj", "{4A03840B-9EBE-47E3-89AB-E0914DF21AFB}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2019 Discord.Net Contributors
+Copyright (c) 2015-2021 Discord.Net Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/guides/concepts/ratelimits.md

@@ -0,0 +1,49 @@
+# Ratelimits
+
+Ratelimits are a core concept of any API - Discords API is no exception. each verified library must follow the ratelimit guidelines.
+
+### Using the ratelimit callback
+
+There is a new property within `RequestOptions` called RatelimitCallback. This callback is called when a request is made via the rest api. The callback is called with a `IRateLimitInfo` parameter:
+
+| Name       | Type            | Description                                                                                                                                        |
+| ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| IsGlobal   | bool            | Whether or not this ratelimit info is global.                                                                                                      |
+| Limit      | int?            | The number of requests that can be made.                                                                                                           |
+| Remaining  | int?            | The number of remaining requests that can be made.                                                                                                 |
+| RetryAfter | int?            | The total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision. |
+| Reset      | DateTimeOffset? | The time at which the rate limit resets.                                                                                                           |
+| ResetAfter | TimeSpan?       | The absolute time when this ratelimit resets.                                                                                                      |
+| Bucket     | string          | A unique string denoting the rate limit being encountered (non-inclusive of major parameters in the route path).                                   |
+| Lag        | TimeSpan?       | The amount of lag for the request. This is used to denote the precise time of when the ratelimit expires.                                          |
+| Endpoint   | string          | The endpoint that this ratelimit info came from.                                                                                                   |
+
+Let's set up a ratelimit callback that will print out the ratelimit info to the console.
+
+```cs
+public async Task MyRatelimitCallback(IRateLimitInfo info)
+{
+    Console.WriteLine($"{info.IsGlobal} {info.Limit} {info.Remaining} {info.RetryAfter} {info.Reset} {info.ResetAfter} {info.Bucket} {info.Lag} {info.Endpoint}");
+}
+```
+
+Let's use this callback in a send message function
+
+```cs
+[Command("ping")]
+public async Task ping()
+{
+    var options = new RequestOptions()
+    {
+        RatelimitCallback = MyRatelimitCallback
+    };
+
+    await Context.Channel.SendMessageAsync("Pong!", options: options);
+}
+```
+
+Running this produces the following output:
+
+```
+False 5 4  2021-09-09 3:48:14 AM +00:00 00:00:05 a06de0de4a08126315431cc0c55ee3dc 00:00:00.9891364 channels/848511736872828929/messages
+```

docs/guides/emoji/emoji.md

@@ -46,14 +46,16 @@ form; this can be obtained in several different ways.
 ### Emoji Declaration
 
 After obtaining the Unicode representation of the emoji, you may
-create the @Discord.Emoji object by passing the string into its
+create the @Discord.Emoji object by passing the string with unicode into its
 constructor (e.g. `new Emoji("👌");` or `new Emoji("\uD83D\uDC4C");`).
 
 Your method of declaring an @Discord.Emoji should look similar to
 this:
-
 [!code-csharp[Emoji Sample](samples/emoji-sample.cs)]
 
+Also you can use `Emoji.Parse()` or `Emoji.TryParse()` methods 
+for parsing emojis from strings like `:heart:`, `<3` or `❤`.
+
 [FileFormat.Info]: https://www.fileformat.info/info/emoji/list.htm
 
 ## Emote
@@ -97,4 +99,4 @@ this:
 ## Additional Information
 
 To learn more about emote and emojis and how they could be used,
-see the documentation of @Discord.IEmote.
+see the documentation of @Discord.IEmote.

docs/guides/guild_events/creating-guild-events.md

@@ -0,0 +1,31 @@
+---
+uid: Guides.GuildEvents.Creating
+title: Creating Guild Events
+---
+
+# Creating guild events
+
+You can create new guild events by using the `CreateEventAsync` function on a guild.
+
+### Parameters
+
+| Name          | Type                              | Summary                                                                      |
+| ------------- | --------------------------------- | ---------------------------------------------------------------------------- |
+| name          | `string`                          | Sets the name of the event.                                                  |
+| startTime     | `DateTimeOffset`                  | Sets the start time of the event.                                            |
+| type          | `GuildScheduledEventType`         | Sets the type of the event.                                                  |
+| privacyLevel? | `GuildScheduledEventPrivacyLevel` | Sets the privacy level of the event                                          |
+| description?  | `string`                          | Sets the description of the event.                                           |
+| endTime?      | `DateTimeOffset?`                 | Sets the end time of the event.                                              |
+| channelId?    | `ulong?`                          | Sets the channel id of the event, only valid on stage or voice channel types |
+| location?     | `string`                          | Sets the location of the event, only valid on external types                 |
+
+Lets create a basic test event.
+
+```cs
+var guild = client.GetGuild(guildId);
+
+var guildEvent = await guild.CreateEventAsync("test event", DateTimeOffset.UtcNow.AddDays(1),  GuildScheduledEventType.External, endTime: DateTimeOffset.UtcNow.AddDays(2), location: "Space");
+```
+
+This code will create an event that lasts a day and starts tomorrow. It will be an external event thats in space.

docs/guides/guild_events/getting-event-users.md

@@ -0,0 +1,16 @@
+---
+uid: Guides.GuildEvents.GettingUsers
+title: Getting Guild Event Users
+---
+
+# Getting Event Users
+
+You can get a collection of users who are currently interested in the event by calling `GetUsersAsync`. This method works like any other get users method as in it returns an async enumerable. This method also supports pagination by user id.
+
+```cs
+// get all users and flatten the result into one collection.
+var users = await event.GetUsersAsync().FlattenAsync();
+
+// get users around the 613425648685547541 id.
+var aroundUsers = await event.GetUsersAsync(613425648685547541, Direction.Around).FlattenAsync();
+```

docs/guides/guild_events/intro.md

@@ -0,0 +1,41 @@
+---
+uid: Guides.GuildEvents.Intro
+title: Introduction to Guild Events
+---
+
+# Guild Events
+
+Guild events are a way to host events within a guild. They offer alot of features and flexibility.
+
+## Getting started with guild events
+
+You can access any events within a guild by calling `GetEventsAsync` on a guild.
+
+```cs
+var guildEvents = await guild.GetEventsAsync();
+```
+
+If your working with socket guilds you can just use the `Events` property:
+
+```cs
+var guildEvents = guild.Events;
+```
+
+There are also new gateway events that you can hook to receive guild scheduled events on.
+
+```cs
+// Fired when a guild event is cancelled.
+client.GuildScheduledEventCancelled += ...
+
+// Fired when a guild event is completed.
+client.GuildScheduledEventCompleted += ...
+
+// Fired when a guild event is started.
+client.GuildScheduledEventStarted += ...
+
+// Fired when a guild event is created.
+client.GuildScheduledEventCreated += ...
+
+// Fired when a guild event is updated.
+client.GuildScheduledEventUpdated += ...
+```

docs/guides/guild_events/modifying-events.md

@@ -0,0 +1,23 @@
+---
+uid: Guides.GuildEvents.Modifying
+title: Modifying Guild Events
+---
+
+# Modifying Events
+
+You can modify events using the `ModifyAsync` method to modify the event, heres the properties you can modify:
+
+| Name         | Type                              | Description                                  |
+| ------------ | --------------------------------- | -------------------------------------------- |
+| ChannelId    | `ulong?`                          | Gets or sets the channel id of the event.    |
+| string       | `string`                          | Gets or sets the location of this event.     |
+| Name         | `string`                          | Gets or sets the name of the event.          |
+| PrivacyLevel | `GuildScheduledEventPrivacyLevel` | Gets or sets the privacy level of the event. |
+| StartTime    | `DateTimeOffset`                  | Gets or sets the start time of the event.    |
+| EndTime      | `DateTimeOffset`                  | Gets or sets the end time of the event.      |
+| Description  | `string`                          | Gets or sets the description of the event.   |
+| Type         | `GuildScheduledEventType`         | Gets or sets the type of the event.          |
+| Status       | `GuildScheduledEventStatus`       | Gets or sets the status of the event.        |
+
+> [!NOTE]
+> All of these properties are optional.

docs/guides/interactions/application-commands/01-getting-started.md

@@ -0,0 +1,32 @@
+---
+uid: Guides.SlashCommands.Intro
+title: Introduction to slash commands
+---
+
+
+# Getting started with application commands.
+
+Welcome! This guide will show you how to use application commands.
+
+## What is an application command?
+
+Application commands consist of three different types. Slash commands, context menu User commands and context menu Message commands.
+Slash commands are made up of a name, description, and a block of options, which you can think of like arguments to a function. The name and description help users find your command among many others, and the options validate user input as they fill out your command.
+Message and User commands are only a name, to the user. So try to make the name descriptive. They're accessed by right clicking (or long press, on mobile) a user or a message, respectively.
+
+All three varieties of application commands have both Global and Guild variants. Your global commands are available in every guild that adds your application. You can also make commands for a specific guild; they're only available in that guild. The User and Message commands are more limited in quantity than the slash commands. For specifics, check out their respective guide pages.
+
+An Interaction is the message that your application receives when a user uses a command. It includes the values that the user submitted, as well as some metadata about this particular instance of the command being used: the guild_id, channel_id, member and other fields. You can find all the values in our data models.
+
+## Authorizing your bot for application commands
+
+There is a new special OAuth2 scope for applications called `applications.commands`. In order to make Application Commands work within a guild, the guild must authorize your application with the `applications.commands` scope. The bot scope is not enough.
+
+Head over to your discord applications OAuth2 screen and make sure to select the `application.commands` scope.
+
+![OAuth2 scoping](slash-commands/images/oauth.png)
+
+From there you can then use the link to add your bot to a server.
+
+> [!NOTE]
+> In order for users in your guild to use your slash commands, they need to have the "Use Slash Command" permission on the guild. 

docs/guides/interactions/application-commands/context-menu-commands/creating-context-menu-commands.md

@@ -0,0 +1,105 @@
+---
+uid: Guides.ContextCommands.Creating
+title: Creating Context Commands
+---
+
+# Creating context menu commands.
+
+There are two kinds of Context Menu Commands: User Commands and Message Commands.
+Each of these have a Global and Guild variant.
+Global menu commands are available for every guild that adds your app. An individual app's global commands are also available in DMs if that app has a bot that shares a mutual guild with the user.
+
+Guild commands are specific to the guild you specify when making them. Guild commands are not available in DMs. Command names are unique per application within each scope (global and guild). That means:
+
+- Your app cannot have two global commands with the same name
+- Your app cannot have two guild commands within the same name on the same guild
+- Your app can have a global and guild command with the same name
+- Multiple apps can have commands with the same names
+
+**Note**: Apps can have a maximum of 5 global context menu commands, and an additional 5 guild-specific context menu commands per guild.
+
+If you don't have the code for a bot ready yet please follow [this guide](https://docs.stillu.cc/guides/getting_started/first-bot.html).
+
+## UserCommandBuilder
+
+The context menu user command builder will help you create user commands. The builder has these available fields and methods:
+
+| Name     | Type     | Description                                                                                      |
+| -------- | -------- | ------------------------------------------------------------------------------------------------ |
+| Name     | string   | The name of this context menu command.                                                           |
+| WithName | Function | Sets the field name.                                                                             |
+| Build    | Function | Builds the builder into the appropriate `UserCommandProperties` class used to make Menu commands |
+
+## MessageCommandBuilder
+
+The context menu message command builder will help you create message commands. The builder has these available fields and methods:
+
+| Name     | Type     | Description                                                                                         |
+| -------- | -------- | --------------------------------------------------------------------------------------------------- |
+| Name     | string   | The name of this context menu command.                                                              |
+| WithName | Function | Sets the field name.                                                                                |
+| Build    | Function | Builds the builder into the appropriate `MessageCommandProperties` class used to make Menu commands |
+
+**Note**: Context Menu command names can be upper and lowercase, and use spaces.
+
+Let's use the user command builder to make a global and guild command.
+
+```cs
+// Let's hook the ready event for creating our commands in.
+client.Ready += Client_Ready;
+
+...
+
+public async Task Client_Ready()
+{
+    // Let's build a guild command! We're going to need a guild so lets just put that in a variable.
+    var guild = client.GetGuild(guildId);
+
+    // Next, lets create our user and message command builder. This is like the embed builder but for context menu commands.
+    var guildUserCommand = new UserCommandBuilder();
+	var guildMessageCommand = new MessageCommandBuilder();
+
+    // Note: Names have to be all lowercase and match the regular expression ^[\w -]{3,32}$
+    guildUserCommand.WithName("Guild User Command");
+	guildMessageCommand.WithName("Guild Message Command");
+
+    // Descriptions are not used with User and Message commands
+    //guildCommand.WithDescription("");
+
+    // Let's do our global commands
+    var globalUserCommand = new UserCommandBuilder();
+    globalCommand.WithName("Global User Command");
+	var globalMessageCommand = new MessageCommandBuilder();
+	globalMessageCommand.WithName("Global Message Command");
+
+
+    try
+    {
+        // Now that we have our builder, we can call the BulkOverwriteApplicationCommandAsync to make our context commands. Note: this will overwrite all your previous commands with this array.
+        await guild.BulkOverwriteApplicationCommandAsync(new ApplicationCommandProperties[]
+        {
+            guildUserCommand.Build(),
+            guildMessageCommand.Build()
+        });
+
+        // With global commands we dont need the guild.
+        await client.BulkOverwriteGlobalApplicationCommandsAsync(new ApplicationCommandProperties[]
+        {
+            globalUserCommand.Build(),
+            globalMessageCommand.Build()
+        })
+    }
+    catch(ApplicationCommandException exception)
+    {
+        // If our command was invalid, we should catch an ApplicationCommandException. This exception contains the path of the error as well as the error message. You can serialize the Error field in the exception to get a visual of where your error is.
+        var json = JsonConvert.SerializeObject(exception.Error, Formatting.Indented);
+
+        // You can send this error somewhere or just print it to the console, for this example we're just going to print it.
+        Console.WriteLine(json);
+    }
+}
+
+```
+
+> [!NOTE]
+> Application commands only need to be created once. They do _not_ have to be 'created' on every startup or connection. The example simple shows creating them in the ready event as it's simpler than creating normal bot commands to register application commands.

docs/guides/interactions/application-commands/context-menu-commands/receiving-context-menu-command-events.md

@@ -0,0 +1,33 @@
+---
+uid: Guides.ContextCommands.Reveiving
+title: Receiving Context Commands
+---
+
+# Receiving Context Menu events
+
+User commands and Message commands have their own unique event just like the other interaction types. For user commands the event is `UserCommandExecuted` and for message commands the event is `MessageCommandExecuted`.
+
+```cs
+// For message commands
+client.MessageCommandExecuted += MessageCommandHandler;
+
+// For user commands
+client.UserCommandExecuted += UserCommandHandler;
+
+...
+
+public async Task MessageCommandHandler(SocketMessageCommand arg)
+{
+    Console.Writeline("Message command received!");
+}
+
+public async Task UserCommandHandler(SocketUserCommand arg)
+{
+    Console.Writeline("User command received!");
+}
+```
+
+User commands contain a SocketUser object called `Member` in their data class, showing the user that was clicked to run the command. 
+Message commands contain a SocketMessage object called `Message` in their data class, showing the message that was clicked to run the command.
+
+Both return the user who ran the command, the guild (if any), channel, etc.