diff --git a/README.md b/README.md index 84829414..fe377c9a 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,8 @@ Individual components of the main package can be installed separately. ### Experimental Packages -Experimental packages provide implementations of non-official released APIs, which are unlisted on official documentation, -not guaranteed to be stable, and may be changed or removed in the future. +Experimental packages provide implementations of non-official released APIs, which are not listed on official documentation, +may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. - Kook.Net.Experimental: [NuGet](https://www.nuget.org/packages/Kook.Net.Experimental/), [Github Packages](https://github.com/gehongyan/Kook.Net/pkgs/nuget/Kook.Net.Experimental) diff --git a/src/Kook.Net.Experimental/Core/Entities/Guilds/GuildProperties.cs b/src/Kook.Net.Experimental/Core/Entities/Guilds/GuildProperties.cs index 4eb3589e..7f0be3cc 100644 --- a/src/Kook.Net.Experimental/Core/Entities/Guilds/GuildProperties.cs +++ b/src/Kook.Net.Experimental/Core/Entities/Guilds/GuildProperties.cs @@ -3,6 +3,12 @@ namespace Kook; /// /// Provides properties that are used to modify an with the specified changes. /// +/// +/// +/// This entity is still in experimental state, which means that it is not for official API implementation +/// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. +/// +/// public class GuildProperties { /// diff --git a/src/Kook.Net.Experimental/Core/Entities/Guilds/IVoiceRegion.cs b/src/Kook.Net.Experimental/Core/Entities/Guilds/IVoiceRegion.cs index 3e3e1810..e43c271a 100644 --- a/src/Kook.Net.Experimental/Core/Entities/Guilds/IVoiceRegion.cs +++ b/src/Kook.Net.Experimental/Core/Entities/Guilds/IVoiceRegion.cs @@ -1,5 +1,14 @@ namespace Kook; +/// +/// Represents a region of which the user connects to when using voice. +/// +/// +/// +/// This entity is still in experimental state, which means that it is not for official API implementation +/// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. +/// +/// public interface IVoiceRegion { /// diff --git a/src/Kook.Net.Experimental/Rest/Entities/Channels/ExperimentalChannelHelper.cs b/src/Kook.Net.Experimental/Rest/Entities/Channels/ExperimentalChannelHelper.cs index 513fca5f..b426abe1 100644 --- a/src/Kook.Net.Experimental/Rest/Entities/Channels/ExperimentalChannelHelper.cs +++ b/src/Kook.Net.Experimental/Rest/Entities/Channels/ExperimentalChannelHelper.cs @@ -5,6 +5,8 @@ namespace Kook.Rest; internal static class ExperimentalChannelHelper { + #region Permissions + /// This channel does not have a parent channel. public static async Task SyncPermissionsAsync(INestedChannel channel, BaseKookClient client, RequestOptions options) @@ -17,4 +19,20 @@ public static async Task SyncPermissionsAsync(INestedChannel channel, BaseKookCl await client.ApiClient.SyncChannelPermissionsAsync(args, options).ConfigureAwait(false); } + #endregion + + #region Voice + + public static async Task DisconnectUserAsync(IVoiceChannel channel, BaseKookClient client, IGuildUser user, RequestOptions options) + { + var args = new DisconnectUserParams + { + UserId = user.Id, + ChannelId = channel.Id + }; + await client.ApiClient.DisconnectUserAsync(args, options).ConfigureAwait(false); + } + + #endregion + } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/Rest/Entities/Channels/RestTextChannelExperimentalExtensions.cs b/src/Kook.Net.Experimental/Rest/Entities/Channels/RestTextChannelExperimentalExtensions.cs index eb120dbe..b7c8ff83 100644 --- a/src/Kook.Net.Experimental/Rest/Entities/Channels/RestTextChannelExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/Rest/Entities/Channels/RestTextChannelExperimentalExtensions.cs @@ -2,6 +2,20 @@ namespace Kook.Rest; public static class RestTextChannelExperimentalExtensions { + /// + /// Syncs the permissions of this nested channel with its parent's. + /// + /// The nested channel whose permissions will be synced. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for syncing channel permissions with its parent's. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task SyncPermissionsAsync(this RestTextChannel channel, RequestOptions options = null) => ExperimentalChannelHelper.SyncPermissionsAsync(channel, channel.Kook, options); } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/Rest/Entities/Channels/RestVoiceChannelExperimentalExtensions.cs b/src/Kook.Net.Experimental/Rest/Entities/Channels/RestVoiceChannelExperimentalExtensions.cs index 09eb5955..00eff1d7 100644 --- a/src/Kook.Net.Experimental/Rest/Entities/Channels/RestVoiceChannelExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/Rest/Entities/Channels/RestVoiceChannelExperimentalExtensions.cs @@ -2,6 +2,37 @@ namespace Kook.Rest; public static class RestVoiceChannelExperimentalExtensions { + /// + /// Syncs the permissions of this nested channel with its parent's. + /// + /// The nested channel whose permissions will be synced. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for syncing channel permissions with its parent's. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task SyncPermissionsAsync(this RestVoiceChannel channel, RequestOptions options = null) => ExperimentalChannelHelper.SyncPermissionsAsync(channel, channel.Kook, options); + /// + /// Disconnects the specified user from the voice channel. + /// + /// The voice channel where the use is connected to. + /// The user to disconnect. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for disconnecting the user from the voice channel. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// + public static Task DisconnectUserAsync(this RestVoiceChannel channel, IGuildUser user, RequestOptions options = null) + => ExperimentalChannelHelper.DisconnectUserAsync(channel, channel.Kook, user, options); } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestGuildExperimentalExtensions.cs b/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestGuildExperimentalExtensions.cs index 03f6e033..fb5b9219 100644 --- a/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestGuildExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestGuildExperimentalExtensions.cs @@ -11,6 +11,12 @@ public static class RestGuildExperimentalExtensions /// The guild to delete. /// The options to be used when sending the request. /// A task that represents the asynchronous deletion operation. + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task DeleteAsync(this RestGuild guild, RequestOptions options = null) => ExperimentalGuildHelper.DeleteAsync(guild, guild.Kook, options); /// diff --git a/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestVoiceRegion.cs b/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestVoiceRegion.cs index 5135617c..83e711de 100644 --- a/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestVoiceRegion.cs +++ b/src/Kook.Net.Experimental/Rest/Entities/Guilds/RestVoiceRegion.cs @@ -6,6 +6,12 @@ namespace Kook.Rest; /// /// Represents a REST-based voice region. /// +/// +/// +/// This entity is still in experimental state, which means that it is not for official API implementation +/// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. +/// +/// [DebuggerDisplay("{DebuggerDisplay,nq}")] public class RestVoiceRegion : RestEntity, IVoiceRegion { diff --git a/src/Kook.Net.Experimental/Rest/ExperimentalClientHelper.cs b/src/Kook.Net.Experimental/Rest/ExperimentalClientHelper.cs index b5057db3..19d4d605 100644 --- a/src/Kook.Net.Experimental/Rest/ExperimentalClientHelper.cs +++ b/src/Kook.Net.Experimental/Rest/ExperimentalClientHelper.cs @@ -40,18 +40,4 @@ public static async Task GetVoiceRegionAsync(BaseKookClient cli } #endregion - - #region Voice - - public static async Task DisconnectUserAsync(BaseKookClient client, IGuildUser user, IVoiceChannel channel, RequestOptions options) - { - var args = new DisconnectUserParams - { - UserId = user.Id, - ChannelId = channel.Id - }; - await client.ApiClient.DisconnectUserAsync(args, options).ConfigureAwait(false); - } - - #endregion } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/Rest/KookRestClientExperimentalExtensions.cs b/src/Kook.Net.Experimental/Rest/KookRestClientExperimentalExtensions.cs index ed66cb4d..2af59447 100644 --- a/src/Kook.Net.Experimental/Rest/KookRestClientExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/Rest/KookRestClientExperimentalExtensions.cs @@ -2,10 +2,61 @@ namespace Kook.Rest; public static class KookRestClientExperimentalExtensions { + /// + /// Gets a collection of the available voice regions. + /// + /// The KOOK rest client instance. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// with all of the available voice regions in this session. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task> GetVoiceRegionsAsync(this KookRestClient client, RequestOptions options = null) => ExperimentalClientHelper.GetVoiceRegionsAsync(client, options); + /// + /// Gets a voice region. + /// + /// The KOOK rest client instance. + /// The identifier of the voice region (e.g. eu-central ). + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the voice region + /// associated with the identifier; null if the voice region is not found. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task GetVoiceRegionAsync(this KookRestClient client, string id, RequestOptions options = null) => ExperimentalClientHelper.GetVoiceRegionAsync(client, id, options); + + /// + /// Creates a guild for the logged-in user who is in less than 10 active guilds. + /// + /// + /// This method creates a new guild on behalf of the logged-in user. + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// + /// The KOOK rest client instance. + /// The name of the new guild. + /// The voice region to create the guild with. + /// The icon of the new guild. + /// The identifier of the guild template to be used to create the new guild. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous creation operation. The task result contains the created guild. + /// public static Task CreateGuildAsync(this KookRestClient client, string name, IVoiceRegion region = null, Stream icon = null, int? templateId = null, RequestOptions options = null) => ExperimentalClientHelper.CreateGuildAsync(client, name, region, icon, templateId, options); diff --git a/src/Kook.Net.Experimental/WebSocket/BaseSocketClientExperimentalExtensions.cs b/src/Kook.Net.Experimental/WebSocket/BaseSocketClientExperimentalExtensions.cs index 31c070b8..cbdaf73a 100644 --- a/src/Kook.Net.Experimental/WebSocket/BaseSocketClientExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/WebSocket/BaseSocketClientExperimentalExtensions.cs @@ -4,6 +4,25 @@ namespace Kook.WebSocket; public static class BaseSocketClientExperimentalExtensions { + /// + /// Creates a guild for the logged-in user who is in less than 10 active guilds. + /// + /// + /// This method creates a new guild on behalf of the logged-in user. + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable,and may be changed or removed in the future. + /// + /// + /// The KOOK rest client instance. + /// The name of the new guild. + /// The voice region to create the guild with. + /// The icon of the new guild. + /// The identifier of the guild template to be used to create the new guild. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous creation operation. The task result contains the created guild. + /// public static Task CreateGuildAsync(this BaseSocketClient client, string name, IVoiceRegion region = null, Stream icon = null, int? templateId = null, RequestOptions options = null) => ExperimentalClientHelper.CreateGuildAsync(client, name, region, icon, templateId, options ?? RequestOptions.Default); diff --git a/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketTextChannelExperimentalExtensions.cs b/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketTextChannelExperimentalExtensions.cs index de80ac18..65d3c48d 100644 --- a/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketTextChannelExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketTextChannelExperimentalExtensions.cs @@ -4,6 +4,20 @@ namespace Kook.WebSocket; public static class SocketTextChannelExperimentalExtensions { + /// + /// Syncs the permissions of this nested channel with its parent's. + /// + /// The nested channel whose permissions will be synced. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for syncing channel permissions with its parent's. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task SyncPermissionsAsync(this SocketTextChannel channel, RequestOptions options = null) => ExperimentalChannelHelper.SyncPermissionsAsync(channel, channel.Kook, options); } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketVoiceChannelExperimentalExtensions.cs b/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketVoiceChannelExperimentalExtensions.cs index cae0ecd3..a33a2a43 100644 --- a/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketVoiceChannelExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/WebSocket/Entities/Channels/SocketVoiceChannelExperimentalExtensions.cs @@ -4,6 +4,38 @@ namespace Kook.WebSocket; public static class SocketVoiceChannelExperimentalExtensions { + /// + /// Syncs the permissions of this nested channel with its parent's. + /// + /// The nested channel whose permissions will be synced. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for syncing channel permissions with its parent's. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task SyncPermissionsAsync(this SocketVoiceChannel channel, RequestOptions options = null) => ExperimentalChannelHelper.SyncPermissionsAsync(channel, channel.Kook, options); + + /// + /// Disconnects the specified user from the voice channel. + /// + /// The voice channel where the use is connected to. + /// The user to disconnect. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation for disconnecting the user from the voice channel. + /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// + public static Task DisconnectUserAsync(this SocketVoiceChannel channel, IGuildUser user, RequestOptions options = null) + => ExperimentalChannelHelper.DisconnectUserAsync(channel, channel.Kook, user, options); } \ No newline at end of file diff --git a/src/Kook.Net.Experimental/WebSocket/Entities/Guilds/SocketGuildExperimentalExtensions.cs b/src/Kook.Net.Experimental/WebSocket/Entities/Guilds/SocketGuildExperimentalExtensions.cs index 06eb4b1a..d2e9c939 100644 --- a/src/Kook.Net.Experimental/WebSocket/Entities/Guilds/SocketGuildExperimentalExtensions.cs +++ b/src/Kook.Net.Experimental/WebSocket/Entities/Guilds/SocketGuildExperimentalExtensions.cs @@ -10,6 +10,12 @@ public static class SocketGuildExperimentalExtensions /// The guild to delete. /// The options to be used when sending the request. /// A task that represents the asynchronous deletion operation. + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// public static Task DeleteAsync(this SocketGuild guild, RequestOptions options = null) => ExperimentalGuildHelper.DeleteAsync(guild, guild.Kook, options); /// @@ -21,6 +27,12 @@ public static Task DeleteAsync(this SocketGuild guild, RequestOptions options = /// /// A task that represents the asynchronous modification operation. /// + /// + /// + /// This method is still in experimental state, which means that it is not for official API implementation + /// usage, may violate the developer rules or policies, not guaranteed to be stable, and may be changed or removed in the future. + /// + /// /// is . public static Task ModifyAsync(this SocketGuild guild, Action func, RequestOptions options = null) => ExperimentalGuildHelper.ModifyAsync(guild, guild.Kook, func, options); diff --git a/src/Kook.Net.WebSocket/Entities/Channels/SocketTextChannel.cs b/src/Kook.Net.WebSocket/Entities/Channels/SocketTextChannel.cs index 02dcc036..244c9617 100644 --- a/src/Kook.Net.WebSocket/Entities/Channels/SocketTextChannel.cs +++ b/src/Kook.Net.WebSocket/Entities/Channels/SocketTextChannel.cs @@ -78,6 +78,9 @@ internal override void Update(ClientState state, Model model) public virtual Task ModifyAsync(Action func, RequestOptions options = null) => ChannelHelper.ModifyAsync(this, Kook, func, options); + private string DebuggerDisplay => $"{Name} ({Id}, Text)"; + internal new SocketTextChannel Clone() => MemberwiseClone() as SocketTextChannel; + #endregion #region Messages @@ -214,9 +217,6 @@ public async Task CreateInviteAsync(InviteMaxAge maxAge = InviteMaxAge. => await ChannelHelper.CreateInviteAsync(this, Kook, maxAge, maxUses, options).ConfigureAwait(false); #endregion - - private string DebuggerDisplay => $"{Name} ({Id}, Text)"; - internal new SocketTextChannel Clone() => MemberwiseClone() as SocketTextChannel; #region Users ///