Releases: gehongyan/Kook.Net
v0.8.0
Update Roadmap
Due to changes in the KOOK API, Bot users can no longer obtain all the necessary basic guild information at startup through the /guild/index
API. Instead, it is now required to traverse each guild via the /guild/view
API. This change can result in a significantly longer startup time and a large number of API requests for Bots that have joined many guilds. Therefore, the current version introduces the KookSocketConfig.StartupCacheFetchMode
configuration item, which defines how the Bot loads the basic guild data needed at startup.
Synchronous
: In synchronous mode, after obtaining a simple list of guilds at client startup, the client fetches the basic data of each guild through the API before triggering theReady
event.Asynchronous
: In asynchronous mode, after obtaining a simple list of guilds at client startup, theReady
event is triggered immediately, and a background task is started to fetch all the basic guild data.Lazy
: In lazy mode, after obtaining a simple list of guilds at client startup, theReady
event is triggered immediately without proactively fetching the basic guild data. When events involving the guild are received from the gateway, the guild's basic data will be fetched through the API if it has not already been obtained.Auto
: In automatic mode, the default setting, the client's startup mode is automatically determined based on the number of guilds the Bot has joined. If the number of guilds reachesLargeNumberOfGuildsThreshold
(default is 50), it will beLazy
; if it reachesSmallNumberOfGuildsThreshold
(default is 5), it will beAsynchronous
; otherwise, it will beSynchronous
. This determination is made each time the Bot connects to the WebSocket.
When not using Synchronous
mode, after the Ready
event, accessing cached guild entities might result in entities that do not fully contain basic guild data. The IsAvailable
property indicates whether the guild entity has fully cached basic data through the API. In such cases, please proactively call the UpdateAsync
method to update the cached guild entity through the API. The basic guild data mentioned above mainly includes the guild's channels, roles, channel permission overrides, and the current user's nickname within guilds.
The entire framework code has been updated to support nullable reference static analysis diagnostics. For the concept of nullable reference types in C#, please refer to Nullable reference types - C# | Microsoft Learn. After updating to the current version, all values that may be null will be marked as nullable types. This may cause some code to generate warnings during compilation, which should be treated as potential null reference exceptions and fixed accordingly.
Additionally, IQuote
has a new implementation MessageReference
, which only contains the ID of the message to be referenced and is used when calling the API in user code. Existing user code that creates Quote
should migrate to MessageReference
as soon as possible.
fileName
has been renamed to filename
; the event parameter Cacheable<SocketMessage, Guid>
has been changed to Cacheable<IMessage, Guid>
; SectionAccessoryMode.Unspecified
is now replaced by null
; Format.StripMarkDown
has been renamed to StripMarkdown
; and the filename
parameter in the SendFileAsync
overload that accepts the Stream
type is now mandatory. Please note that these changes may cause compilation errors and should be fixed accordingly.
Additions
KookSocketConfig
adds theStartupCacheFetchMode
,LargeNumberOfGuildsThreshold
, andSmallNumberOfGuildsThreshold
configuration items to customize how the Bot's Socket client fetches the basic guild data needed at startup via the API.- Two new configuration properties
AutoUpdateRolePositions
andAutoUpdateChannelPositions
have been added toKookSocketConfig
, defaulting tofalse
. When enabled, the client will automatically fetch data via the API upon receiving related events to maintain the cached role and channel sorting information. Embed
addsCardEmbed
.- Card entities and builders now implement
IEquatable<T>
. SocketSelfUser
now implementsIUpdateable
.- Added
IGuild.RecommendInfo.Certifications
. IQuote
has a new implementationMessageReference
, which only contains the ID of the message to be referenced and is used when calling the API in user code.- Support for the event types
embeds_append
,sort_channel
,updated_server_type
,batch_added_channel
,batch_updated_channel
,batch_deleted_channel
,live_status_changed
,PERSON
typedupdated_guild
,add_guild_mute
,delete_guild_mute
,unread_count_changed
has been added, but it is not yet confirmed whether these events will actually be dispatched.
Fixes
- Fixed the issue where the author of private messages was incorrect.
- Fixed the issue where
SocketUserMessage.Quote.Author
could be null. - Fixed the issue where Tags were missing corresponding values when referencing nonexistent entities in messages.
- Fixed the issue where the voice client failed to handle undefined events, causing stream crashes.
- Fixed the issue where parsing newly introduced mixed media messages failed.
- Corrected the behavior of updating user nicknames.
Changes
- Enabled nullable reference types feature. For the concept of nullable reference types in C#, please refer to Nullable reference types - C# | Microsoft Learn.
- Various validations for the card builder are now deferred to the
Build
call. - The types of properties involving lists in cards have been changed to
IList<T>
. Quote.Empty
and its public constructor have been marked asObsolete
, andMessageReference
should be used instead.fileName
has been renamed tofilename
.- The
filename
parameter in theSendFileAsync
overload that accepts theStream
type is now mandatory. BaseSocketClient._baseConfig
has been renamed toBaseConfig
.- The event parameter
Cacheable<SocketMessage, Guid>
has been changed toCacheable<IMessage, Guid>
to address the issue of entity download failure. SectionAccessoryMode.Unspecified
has been removed; please usenull
instead.Format.StripMarkDown
has been renamed toStripMarkdown
, and the original method has been marked asObsolete
.Format.StripMarkdown
now removes hyphens-
.
Others
- Added a reference to
PolySharp
on .NET 7 and earlier target frameworks to support the implementation of some new features on older frameworks. - Added integration tests for some Socket events.
Full Changelog: v0.7.0...v0.8.0
v0.7.0
Update Path
The KOOK client now supports sending messages within voice channels. As a result, the following APIs have been modified:
CreateVoiceChannelProperties
now inherits fromCreateTextChannelProperties
.ModifyVoiceChannelProperties
now inherits fromModifyTextChannelProperties
.IVoiceChannel
now inherits fromITextChannel
.- The value of
ChannelPermissions.Voice
now includes permissions for text channels. - The
SocketTextChannel.GetMessagesAsync
series of methods are now virtual methods, to be overridden bySocketVoiceChannel
.
It's important to note that, due to limitations in the KOOK API, fetching message history and pinning messages are not supported within voice channels via the API. Therefore, calling GetMessagesAsync
and GetPinnedMessagesAsync
methods from IMessageChannel
on voice channels is not supported.
Additionally, while voice channels support operations on Topic
and SlowModeInterval
at the API level, the KOOK client currently does not reflect these capabilities.
Creating channels does not immediately support specifying a Topic. The Topic
property in CreateTextChannelProperties
has been removed and does not take effect. Please use the ITextChannel.ModifyAsync
method to modify the channel after creation.
Added
- Added support for defining card messages via XML. (#9 by @LiamSho)
IVoiceChannel
now inherits fromITextChannel
, with relevant implementations updated.- Added
SentRequest
event toBaseKookClient
. - Added non-null result prompts for parsing card message-related
Try*
methods.
Fixed
- Corrected the issue with
ConnectionManager
incorrectly updatingState
whenDisconnected
.
Changes
- Removed the
Topic
property fromCreateTextChannelProperties
.
Misc
- Marked the project as not supporting AOT and assembly trimming.
- Added example project
Kook.Net.Samples.CardMarkup
. (#9 by @LiamSho) - Added documentation for defining card messages via XML. (#9 by @LiamSho)
- Added Logo.
New Contributors
- @LiamSho made their first contribution in #9
Full Changelog: v0.6.0...v0.7.0
v0.6.0
Update Path
In KOOK, mentioning voice channels in text messages is not supported, meaning IVoiceChannel
should not be derived from IMentionable
interface. Incorrect usage of mentioning IVoiceChannel
should be removed or modified.
The name of the cancellation token has been changed from CancelToken
to CancellationToken
. Existing methods, variables, properties, and parameters related to cancellation token should be updated.
Added
- Added connection and streaming for voice channels.
Fixed
- Fixed an issue where
KookSocketClient
did not correctly handleConnectionState
when casted toIKookClient
orBaseKookClient
.
Changes
IVoiceChannel
no longer derived fromIMentionable
interface.- Renamed the name of methods, variables, properties, and parameters from
CancelToken
toCancellationToken
.
Misc
- Updated document template, added example project page, and added voice streaming documentation.
Full Changelog: v0.5.5...v0.6.0
v0.5.5
Update Path
RequireUserAttribute
no longer supports construction via the IUser
parameter; please use IUser.Id
instead.
Added
- Added
RequireRoleAttribute
as a precondition in the text command framework. - Added
Aliases
,Summary
, andRemarks
properties, and optional parameters toCommandAttribute
in the text command framework.
Fixed
- Fixed an issue where exceptions during data download at Bot startup were not properly outputted to the log.
Changed
- Removed the unrealistic constructor on
RequireUserAttribute
that accepted anIUser
parameter.
Full Changelog: v0.5.4...v0.5.5
v0.5.4
Update Path
The set accessibility of the AuthTokenType
and AuthToken
properties in the KookRestApiClient
has been changed to
private. Modifying these properties directly in user code may result in framework runtime exceptions. If you need to log
in with a different authentication on the KOOK gateway, please re-login using LoginAsync
after calling LogoutAsync
.
Added
- Added
HasAnnualBuff
,IsSystemUser
, andNameplates
properties to theIUser
interface. - Added
BackgroundColor
property to theUserTag
. - Added support for parsing interactive emojis.
Changed
- Changed the set accessibility of the
AuthTokenType
andAuthToken
properties in theKookRestApiClient
to private.
Full Changelog: v0.5.3...v0.5.4
v0.5.3
Update Path
The IVoiceChannel.ServerUrl
property has been moved to the IAudioChannel
interface. All usages of this property need to be updated.
Added
- Added voice region properties to the
IAudioChannel
interface. - Added support for modifying voice region properties in the
IVoiceChannel.ModifyAsync
method. - Added parameterized constructors to card, module, and element builders.
Changed
- The
IVoiceChannel.ServerUrl
property has been moved to theIAudioChannel
interface. - Removed unintentionally provided public set accessors on some properties.
Fixed
- Fixed incorrect build validation conditions for
SectionModuleBuild
.
Other
- Replaced the Moq testing mock framework with NSubstitute.
- Added Docker usage examples.
- Added support for targeting .NET 8.
Full Changelog: v0.5.2...v0.5.3
v0.5.2
Update Path
The parameter Action<string>
of the ModifyEmoteNameAsync
method has been changed to string
. All usages of this method need to be updated.
Fixed
- Fixed an issue where incorrect comparison of
SocketReaction
caused the reaction cannot be removed from the cached message when a reaction is removed. - Fixed an issue where the Socket client did not correctly send the close code when disconnecting.
- Fixed an issue where the results were incorrect when querying messages after a reference message in the
GetMessagesAsync
method. - Fixed an issue where the
ModifyEmoteNameAsync
method did not correctly rename guild emotes.
Misc
- Completed the quick reference guide.
- Added actual functionality to the sample program
SimpleBot
, which can respond to a simple command, reply with buttons, and respond to button click events. - Added examples for Visual Basic and F#.
Full Changelog: v0.5.1...v0.5.2
v0.5.1
Added
- Introduced new methods
SocketGuild.GetCategoryChannel
andRestGuild.GetCategoryChannelAsync
.
Fixed
- Resolved an issue where the
GetJumpUrl
method was returning incorrect results. - Corrected the value of
KookConfig.MaxMessagesPerBatch
that was not being set correctly. - Fixed the incorrect deserialization of deleted quotes.
- Addressed the problem where the
RequestOptions
parameter ofMoveUsersAsync
was not optional. - Fixed the failure of the
MoveUsersAsync
method. - Fixed an issue where modifying channel permissions immediately after creating them on a
SocketGuildChannel
could result in failure without any error information.
Optimized
- Optimized the internal implementation of the
GetDirectMessageAsync
method. - Ensured consistent string representation for
langword
in comments.
Full Changelog: v0.5.0...v0.5.1
v0.5.0
Update Path
For the sake of convenience, this version has made adjustments to the parameter types passed in some events in BaseSocketClient
. Please refer to the appendix at the end of the document for specific changes to event parameters. Applications involving these events need to be updated accordingly.
The enum values and properties representing key accounts in GuildFeature
and GuildFeatures
have been renamed for more accurate naming. GuildPermissions
has been refactored as a struct, and the type of the RoleProperties.Permissions
property has been changed accordingly. The type of RestGuild.Channels
was incorrectly declared as a dictionary with values of type RestChannel
, and has been corrected to a dictionary with values of type RestGuildChannel
. The return type of some methods on KookSocketClient
was previously ValueTask
, but has now been unified to Task
. Usages involving these APIs need to be updated accordingly.
Added
- Added
GuildFeature.Partner
enum value andGuildFeatures.IsPartner
property. - Added
IGuild.Banner
property. - Added
CurrentUserNickname
,CurrentUserDisplayName
, andCurrentUserRoles
properties onRestGuild
. - Added
SyncPermissionsAsync
method onINestedChannel
. - Added
DownloadVoiceStatesAsync
andDownloadBoostSubscriptionsAsync
abstract methods onBaseSocketClient
. - Added
TextChannels
,VoiceChannels
, andCategoryChannels
properties onRestGuild
.
Changed
.
- Renamed
GuildFeature.Ka
toGuildFeature.KeyAccount
andGuildFeatures.IsKa
toGuildFeatures.IsKeyAccount
. - Changed
GuildPermissions
to a struct and changedRoleProperties.Permissions
to typeGuildPermissions?
. - For convenience, some events in
BaseSocketClient
have been changed or added with event parameters. See the appendix at the end of the document for details. - Changed all parameters of
DownloadBoostSubscriptionsAsync
method onBaseSocketClient
to optional parameters. - Changed the type of
RestGuild.Channels
toImmutableDictionary<ulong, RestGuildChannel>
. - Changed the return type of
GetChannelAsync
,GetDMChannelAsync
,GetDMChannelsAsync
, andGetUserAsync
methods
onKookSocketClient
toTask<*>
.
Fixed
- Fixed an issue where some APIs were unable to correctly parse the string
1
or0
when returning a bool type. - Fixed an issue where
IGuild.DefaultChannelId
was not correctly set to the actual default text channel configured on the server. - Fixed an issue where
SocketGuild.CurrentUser
was null when downloading the server user list. - Fixed an issue where
IsOnline
andActiveClient
onSocketUser
could throw null reference exceptions. - Fixed an issue where messages of type
MessageType.Poke
were not correctly parsed. - Fixed an issue where the request bucket was not handling HTTP 429 Too Many Requests errors correctly.
Optimized
- Optimized the debugger display text of
Cacheable
. FileAttachment.Stream
can now be reused.- The
SendFileAsync
andReplyFileAsync
methods will now cache the asset URI created forFileAttachment
attachments created through files or streams before multiple sends, to avoid uploading the same file repeatedly.
Misc
- Fixed some strange code indentation.
- Changed the document theme.
- Added a separate workflow for updating the documentation that depends on the
doc
branch. - Added an API quick reference document.
- Added missing permission values to permission-related unit tests.
Appendix
Event parameter changes in BaseSocketClient
:
-
ReactionAdded
andReactionRemoved
ISocketMessageChannel
→SocketTextChannel
- Add
Cacheable<SocketGuildUser, ulong>
representing the user who added or removed the reaction
-
DirectReactionAdded
andDirectReactionRemoved
- Add
Cacheable<SocketUser, ulong>
representing the user who added or removed the reaction
- Add
-
MessageReceived
- Add
SocketGuildUser
representing the user who sent the message - Add
SocketTextChannel
representing the text channel where the message was sent
- Add
-
MessageDeleted
、MessageUpdated
、MessagePinned
与MessageUnpinned
ISocketMessageChannel
→SocketTextChannel
-
DirectMessageReceived
- Add
SocketUser
representing the user who sent the message - Add
SocketDMChannel
representing the DM channel where the message was sent
- Add
-
DirectMessageDeleted
Cacheable<IDMChannel, Guid>
→Cacheable<SocketDMChannel, ulong>
- Add
Cacheable<SocketUser, ulong>
representing the user who sent the message
-
DirectMessageUpdated
IDMChannel
→Cacheable<SocketDMChannel, ulong>
- Add
Cacheable<SocketUser, ulong>
representing the user who sent the message
Full Changelog: v0.4.1...v0.5.0
v0.4.1
Fixed
- Fixed an issue where the corresponding permission overwrites of
SocketGuildChannel.UserPermissionOverwrites
andSocketGuildChannel.RolePermissionOverwrites
were not removed when a user left the guild or a role was deleted.
Full Changelog: v0.4.0...v0.4.1