From b474cf64fd9b8a60b54de86f94e463a795b05494 Mon Sep 17 00:00:00 2001 From: Red-K0 <114494949+Red-K0@users.noreply.github.com> Date: Sun, 12 Jul 2026 01:58:54 +0300 Subject: [PATCH 1/2] Large commit: - Added significant amounts of documentation to RestClient, channel and message types, and more. - Added some missing / newly-added properties and JSON objects. - Renamed certain flag values for more consistent styling. - Obsoleted certain deprecated properties. - Added some missing flags. --- NetCord/Attachment.cs | 29 +- NetCord/AttachmentExpirationInfo.cs | 12 + NetCord/AttachmentFlags.cs | 28 +- NetCord/BaseTheme.cs | 32 ++ NetCord/ChannelFlags.cs | 6 +- NetCord/Channels/IGuildChannel.cs | 17 + NetCord/Channels/INamedChannel.cs | 6 + NetCord/Channels/IUnknownChannel.cs | 6 + NetCord/Channels/IUnknownGuildChannel.cs | 3 + .../Guild/AnnouncementGuildChannel.cs | 3 + .../Guild/DirectoryGuildChannel.cs | 3 + .../TextChannels/Guild/ForumGuildChannel.cs | 47 ++- .../TextChannels/Guild/TextGuildChannel.cs | 33 ++ .../Guild/Threads/AnnouncementGuildThread.cs | 3 + .../Guild/Threads/ForumGuildThread.cs | 6 + .../TextChannels/Guild/Threads/GuildThread.cs | 36 +- .../Guild/Threads/GuildThreadMetadata.cs | 36 ++ .../Guild/Threads/IUnknownGuildThread.cs | 3 + .../Guild/Threads/PrivateGuildThread.cs | 3 + .../Guild/Threads/PublicGuildThread.cs | 9 + .../Guild/Threads/UnknownGuildThread.cs | 3 + NetCord/ClipAttachment.cs | 33 ++ NetCord/CustomEmoji.cs | 21 ++ NetCord/EmbedAuthor.cs | 6 +- NetCord/EmbedField.cs | 2 +- NetCord/Emoji.cs | 9 + NetCord/EmojiReference.cs | 6 + NetCord/ForumGuildChannelDefaultReaction.cs | 16 + NetCord/ForumLayoutType.cs | 14 + NetCord/ForumTag.cs | 28 ++ NetCord/GuildChannelMention.cs | 18 + NetCord/GuildEmoji.cs | 9 + NetCord/GuildSticker.cs | 12 + NetCord/GuildUser.cs | 4 +- NetCord/ImageAttachment.cs | 19 +- NetCord/ImageFormat.cs | 28 +- NetCord/ImageUrl.cs | 26 +- NetCord/InteractionResolvedData.cs | 20 +- NetCord/JsonModels/JsonAttachment.cs | 15 + NetCord/JsonModels/JsonGuildThreadMetadata.cs | 3 + NetCord/JsonModels/JsonMessage.cs | 3 + NetCord/JsonModels/JsonSharedClientTheme.cs | 18 + NetCord/MessageFlags.cs | 3 + NetCord/MessagePoll.cs | 26 ++ NetCord/MessagePollAnswer.cs | 11 + NetCord/MessagePollAnswerCount.cs | 14 + NetCord/MessagePollLayoutType.cs | 6 + NetCord/MessagePollMedia.cs | 10 + NetCord/MessagePollResults.cs | 11 + NetCord/MessageReaction.cs | 21 ++ NetCord/MessageReactionCountDetails.cs | 7 +- NetCord/MessageReactionEmoji.cs | 12 + NetCord/MessageSnapshotMessage.cs | 2 +- NetCord/MessageSticker.cs | 6 + NetCord/MessageType.cs | 6 + NetCord/PermissionOverwrite.cs | 15 + NetCord/PermissionOverwriteType.cs | 3 + NetCord/Permissions.cs | 51 ++- NetCord/Rest/AllowedMentionsProperties.cs | 23 +- NetCord/Rest/AttachmentProperties.cs | 43 ++- NetCord/Rest/EmbedAuthorProperties.cs | 13 +- NetCord/Rest/EmbedFieldProperties.cs | 11 +- NetCord/Rest/EmbedFooterProperties.cs | 8 +- NetCord/Rest/EmbedImageProperties.cs | 10 +- NetCord/Rest/EmbedProperties.cs | 31 +- NetCord/Rest/EmbedThumbnailProperties.cs | 10 +- .../Rest/ForumGuildThreadMessageProperties.cs | 6 + NetCord/Rest/GuildStickerOptions.cs | 11 + NetCord/Rest/GuildStickerProperties.cs | 4 +- NetCord/Rest/GuildThreadUser.cs | 7 + NetCord/Rest/IMessageProperties.cs | 18 + NetCord/Rest/IncomingWebhook.cs | 10 + NetCord/Rest/MessageCall.cs | 10 + NetCord/Rest/MessageOptions.cs | 9 + NetCord/Rest/RestClient.Application.cs | 11 + ...lient.ApplicationRoleConnectionMetadata.cs | 13 + NetCord/Rest/RestClient.AuditLog.cs | 6 + NetCord/Rest/RestClient.AutoModeration.cs | 35 ++ NetCord/Rest/RestClient.Channel.cs | 314 ++++++++++++++++++ NetCord/Rest/RestClient.Webhook.cs | 135 +++++++- NetCord/Rest/RestGuild.cs | 4 +- NetCord/Rest/RestMessage.cs | 66 +++- NetCord/Rest/RestRequestProperties.cs | 3 + NetCord/Rest/StickerPack.cs | 26 ++ NetCord/Rest/Webhook.cs | 61 ++++ NetCord/Rest/WebhookClient.cs | 15 + NetCord/Rest/WebhookClientConfiguration.cs | 6 + NetCord/Rest/WebhookMessageProperties.cs | 18 + NetCord/Rest/WebhookOptions.cs | 8 + NetCord/Rest/WebhookProperties.cs | 8 + NetCord/Rest/WebhookType.cs | 14 + NetCord/RoleSubscriptionData.cs | 5 +- NetCord/SharedClientTheme.cs | 31 ++ NetCord/SortOrderType.cs | 10 + NetCord/StandardSticker.cs | 12 + NetCord/Sticker.cs | 21 ++ NetCord/StickerFormat.cs | 24 +- NetCord/ThreadArchiveDuration.cs | 18 + NetCord/ThreadCurrentUser.cs | 12 +- NetCord/ThreadUser.cs | 23 +- NetCord/User.cs | 4 +- NetCord/VideoQualityMode.cs | 12 +- NetCord/VoiceAttachment.cs | 5 + Tests/MentionTest/TryFormat.cs | 2 +- .../NetCord.Test/Commands/StrangeCommands.cs | 2 +- 105 files changed, 1819 insertions(+), 167 deletions(-) create mode 100644 NetCord/BaseTheme.cs create mode 100644 NetCord/ClipAttachment.cs create mode 100644 NetCord/JsonModels/JsonSharedClientTheme.cs create mode 100644 NetCord/SharedClientTheme.cs diff --git a/NetCord/Attachment.cs b/NetCord/Attachment.cs index 461a6512d..98e503546 100644 --- a/NetCord/Attachment.cs +++ b/NetCord/Attachment.cs @@ -1,5 +1,10 @@ +using NetCord.Rest; + namespace NetCord; +/// +/// Represents a message attachment, and its contained data. +/// public class Attachment(JsonModels.JsonAttachment jsonModel) : Entity, IJsonModel { JsonModels.JsonAttachment IJsonModel.JsonModel => _jsonModel; @@ -8,37 +13,37 @@ public class Attachment(JsonModels.JsonAttachment jsonModel) : Entity, IJsonMode public override ulong Id => _jsonModel.Id; /// - /// Name of the attachment. + /// Name of the attachment (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). /// public string FileName => _jsonModel.FileName; /// - /// Title of the attachment. + /// The title of the attachment. /// public string? Title => _jsonModel.Title; /// - /// Description for the attachment (max 1024 characters). + /// Description for the attachment (max 1024 characters for attachments sent by message, max 200 characters for attachments used for sticker creation). /// public string? Description => _jsonModel.Description; /// - /// The attachment's media type. + /// The attachment's media (MIME) type. /// public string? ContentType => _jsonModel.ContentType; /// - /// Size of file in bytes. + /// The attachment's size in bytes. /// public long Size => _jsonModel.Size; /// - /// Source url of file. + /// The attachment's source URL. /// public string Url => _jsonModel.Url; /// - /// A proxied url of file. + /// The attachment's source URL, proxied through Discord's CDN. /// public string ProxyUrl => _jsonModel.ProxyUrl; @@ -47,16 +52,24 @@ public class Attachment(JsonModels.JsonAttachment jsonModel) : Entity, IJsonMode /// public bool Ephemeral => _jsonModel.Ephemeral; + /// + /// Additional information about the attachment's type. + /// public AttachmentFlags Flags => _jsonModel.Flags; + /// + /// Returns expiration and issue info for the attachment's source URL. + /// public AttachmentExpirationInfo GetExpirationInfo() => new(Url); - public static Attachment CreateFromJson(JsonModels.JsonAttachment jsonModel) + public static Attachment CreateFromJson(JsonModels.JsonAttachment jsonModel, RestClient client) { if (jsonModel.Width.HasValue) return new ImageAttachment(jsonModel); else if (jsonModel.DurationSeconds.HasValue) return new VoiceAttachment(jsonModel); + else if (jsonModel.ClipCreatedAt.HasValue) + return new ClipAttachment(jsonModel, client); else return new Attachment(jsonModel); } diff --git a/NetCord/AttachmentExpirationInfo.cs b/NetCord/AttachmentExpirationInfo.cs index 711ed4c24..dde174907 100644 --- a/NetCord/AttachmentExpirationInfo.cs +++ b/NetCord/AttachmentExpirationInfo.cs @@ -3,6 +3,9 @@ namespace NetCord; +/// +/// Contains information on a CDN URL's issue and expiry. +/// public class AttachmentExpirationInfo { public AttachmentExpirationInfo(string url) @@ -13,9 +16,18 @@ public AttachmentExpirationInfo(string url) Signature = query["hm"]!; } + /// + /// A timestamp indicating when the CDN URL will expire. + /// public DateTimeOffset ExpiresAt { get; } + /// + /// A timestamp indicating when the CDN URL was issued. + /// public DateTimeOffset IssuedAt { get; } + /// + /// A unique signature, valid until the CDN URL's expiration. + /// public string Signature { get; } } diff --git a/NetCord/AttachmentFlags.cs b/NetCord/AttachmentFlags.cs index 244b58c5d..21c092b6f 100644 --- a/NetCord/AttachmentFlags.cs +++ b/NetCord/AttachmentFlags.cs @@ -1,20 +1,36 @@ namespace NetCord; +/// +/// A bitfield with additional information about an attachment. +/// [Flags] public enum AttachmentFlags { /// - /// This attachment is a clip. + /// The attachment is a clip from a stream. /// - IsClip = 1 << 0, + Clip = 1 << 0, /// - /// This attachment is a thumbnail. + /// The attachment is the thumbnail of a media channel thread. /// - IsThumbnail = 1 << 1, + /// + /// Media channel thumbnails are displayed in the channel grid, but not on the thread message. + /// + Thumbnail = 1 << 1, /// - /// This attachment has been edited using the remix feature on mobile. + /// The attachment has been edited using the remix feature on mobile (deprecated). /// - IsRemix = 1 << 2, + Remix = 1 << 2, + + /// + /// The attachment was marked as a spoiler, and remains blurred until clicked. + /// + Spoiler = 1 << 3, + + /// + /// The attachment is an animated image. + /// + Animated = 1 << 5 } diff --git a/NetCord/BaseTheme.cs b/NetCord/BaseTheme.cs new file mode 100644 index 000000000..80301aa92 --- /dev/null +++ b/NetCord/BaseTheme.cs @@ -0,0 +1,32 @@ +namespace NetCord; + +/// +/// Specifies a 's base theme. +/// +public enum BaseTheme : byte +{ + /// + /// No base theme specified, equivalent to . + /// + Unset = 0, + + /// + /// Equivalent to Discord's 'Ash' theme. + /// + Dark = 1, + + /// + /// Equivalent to Discord's 'Light' theme. + /// + Light = 2, + + /// + /// Equivalent to Discord's 'Dark' theme. + /// + Darker = 3, + + /// + /// Equivalent to Discord's 'Onyx' theme. + /// + Midnight = 4 +} diff --git a/NetCord/ChannelFlags.cs b/NetCord/ChannelFlags.cs index 0f6d4b87f..0dd653fa8 100644 --- a/NetCord/ChannelFlags.cs +++ b/NetCord/ChannelFlags.cs @@ -9,7 +9,7 @@ public enum ChannelFlags GuildFeedRemoved = 1 << 0, /// - /// Post is pinned to its forum channel. + /// Whether a thread is pinned to the top of its parent or . /// Pinned = 1 << 1, @@ -19,7 +19,7 @@ public enum ChannelFlags ActiveChannelsRemoved = 1 << 2, /// - /// Forum requires a tag for posts. + /// Whether a tag is required to be specified when creating a thread in a or . /// RequireTag = 1 << 4, @@ -69,7 +69,7 @@ public enum ChannelFlags Broadcasting = 1 << 14, /// - /// Channel has no download options for media, media channel exclusive. + /// Hides the embedded media download options. Available only for media channels. /// HideMediaDownloadOptions = 1 << 15, } diff --git a/NetCord/Channels/IGuildChannel.cs b/NetCord/Channels/IGuildChannel.cs index 768efa393..ae016567b 100644 --- a/NetCord/Channels/IGuildChannel.cs +++ b/NetCord/Channels/IGuildChannel.cs @@ -3,10 +3,27 @@ namespace NetCord; +/// +/// Represents a channel within a guild. +/// public partial interface IGuildChannel : INamedChannel { + /// + /// The ID corresponding to the channel's parent guild. + /// public ulong GuildId { get; } + + /// + /// The channel's position within the guild channel list. + /// + /// + /// If two or more channels share a position, they are instead sorted by their ID. + /// public int? Position { get; } + + /// + /// A list of explicit permission overwrites for specified members and roles. + /// public IReadOnlyDictionary PermissionOverwrites { get; } public static IGuildChannel CreateFromJson(JsonChannel jsonChannel, ulong guildId, RestClient client) diff --git a/NetCord/Channels/INamedChannel.cs b/NetCord/Channels/INamedChannel.cs index 423222711..35ec24ba4 100644 --- a/NetCord/Channels/INamedChannel.cs +++ b/NetCord/Channels/INamedChannel.cs @@ -1,7 +1,13 @@ namespace NetCord; +/// +/// Represents a named channel. +/// public interface INamedChannel : IEntity, ISpanFormattable { + /// + /// The name of the channel object, between 1 and 100 characters. + /// public string Name { get; } public string ToString(); diff --git a/NetCord/Channels/IUnknownChannel.cs b/NetCord/Channels/IUnknownChannel.cs index 36e7dcf64..b121e9554 100644 --- a/NetCord/Channels/IUnknownChannel.cs +++ b/NetCord/Channels/IUnknownChannel.cs @@ -1,6 +1,12 @@ namespace NetCord; +/// +/// Represents a channel of an unresolved type. +/// public interface IUnknownChannel : IEntity, ISpanFormattable { + /// + /// The type of the unresolved channel. + /// public ChannelType Type { get; } } diff --git a/NetCord/Channels/IUnknownGuildChannel.cs b/NetCord/Channels/IUnknownGuildChannel.cs index 647f9a8e1..b335bf516 100644 --- a/NetCord/Channels/IUnknownGuildChannel.cs +++ b/NetCord/Channels/IUnknownGuildChannel.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Represents a guild channel of an unresolved type. +/// public partial interface IUnknownGuildChannel : IUnknownChannel, IGuildChannel { } diff --git a/NetCord/Channels/TextChannels/Guild/AnnouncementGuildChannel.cs b/NetCord/Channels/TextChannels/Guild/AnnouncementGuildChannel.cs index b505ecdd5..7bfd915fa 100644 --- a/NetCord/Channels/TextChannels/Guild/AnnouncementGuildChannel.cs +++ b/NetCord/Channels/TextChannels/Guild/AnnouncementGuildChannel.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a channel that users can follow and crosspost from into their own servers. Formerly known as news channels. +/// public partial class AnnouncementGuildChannel(JsonModels.JsonChannel jsonModel, ulong guildId, RestClient client) : TextGuildChannel(jsonModel, guildId, client) { } diff --git a/NetCord/Channels/TextChannels/Guild/DirectoryGuildChannel.cs b/NetCord/Channels/TextChannels/Guild/DirectoryGuildChannel.cs index a8e0f13d6..9e149d0e1 100644 --- a/NetCord/Channels/TextChannels/Guild/DirectoryGuildChannel.cs +++ b/NetCord/Channels/TextChannels/Guild/DirectoryGuildChannel.cs @@ -3,6 +3,9 @@ namespace NetCord; +/// +/// Represents a hub channel, with listed guilds. +/// public partial class DirectoryGuildChannel(JsonChannel jsonModel, ulong guildId, RestClient client) : TextChannel(jsonModel, client), IGuildChannel { public ulong GuildId { get; } = guildId; diff --git a/NetCord/Channels/TextChannels/Guild/ForumGuildChannel.cs b/NetCord/Channels/TextChannels/Guild/ForumGuildChannel.cs index 18b19650b..65dabf7ed 100644 --- a/NetCord/Channels/TextChannels/Guild/ForumGuildChannel.cs +++ b/NetCord/Channels/TextChannels/Guild/ForumGuildChannel.cs @@ -3,6 +3,9 @@ namespace NetCord; +/// +/// Represents a forum channel within a guild. +/// public partial class ForumGuildChannel : Channel, IGuildChannel { public ForumGuildChannel(JsonChannel jsonModel, ulong guildId, RestClient client) : base(jsonModel, client) @@ -20,15 +23,57 @@ public ForumGuildChannel(JsonChannel jsonModel, ulong guildId, RestClient client public int? Position => _jsonModel.Position; public IReadOnlyDictionary PermissionOverwrites { get; } public string Name => _jsonModel.Name!; + + /// + /// The channel topic, between 0 and 4096 characters. Can be . + /// public string? Topic => _jsonModel.Topic; + + /// public bool Nsfw => _jsonModel.Nsfw.GetValueOrDefault(); - public ulong? LastMessageId => _jsonModel.LastMessageId; + + /// + /// The ID of the last thread created in this channel. Can be . + /// + /// + /// May not point to an existing or valid thread. + /// + public ulong? LastThreadId => _jsonModel.LastMessageId; + + /// public int Slowmode => _jsonModel.Slowmode.GetValueOrDefault(); + + /// public ulong? ParentId => _jsonModel.ParentId; + + /// + /// When the last pinned message was pinned. Can be . + /// public DateTimeOffset? LastPin => _jsonModel.LastPin; + + /// + /// The set of tags available for use in the channel. + /// public IReadOnlyList AvailableTags { get; } + + /// + /// The emoji to display by default as the add reaction button. + /// public ForumGuildChannelDefaultReaction? DefaultReactionEmoji { get; } + + /// . public int DefaultThreadSlowmode => _jsonModel.DefaultThreadSlowmode.GetValueOrDefault(); + + /// + /// The sort order to use for threads within the channel. + /// + /// + /// If set to , indicates no preferred sort order has been set. + /// public SortOrderType? DefaultSortOrder => _jsonModel.DefaultSortOrder; + + /// + /// The default layout to use for threads within the channel. + /// public ForumLayoutType DefaultForumLayout => _jsonModel.DefaultForumLayout.GetValueOrDefault(); } diff --git a/NetCord/Channels/TextChannels/Guild/TextGuildChannel.cs b/NetCord/Channels/TextChannels/Guild/TextGuildChannel.cs index 7a685967e..d14e85311 100644 --- a/NetCord/Channels/TextChannels/Guild/TextGuildChannel.cs +++ b/NetCord/Channels/TextChannels/Guild/TextGuildChannel.cs @@ -2,16 +2,49 @@ namespace NetCord; +/// +/// Represents a text channel within a guild. +/// public partial class TextGuildChannel(JsonModels.JsonChannel jsonModel, ulong guildId, RestClient client) : TextChannel(jsonModel, client), IGuildChannel { public ulong GuildId { get; } = guildId; + public int? Position => _jsonModel.Position; + public IReadOnlyDictionary PermissionOverwrites { get; } = jsonModel.PermissionOverwrites.ToDictionaryOrEmpty(p => p.Id, p => new PermissionOverwrite(p)); + public string Name => _jsonModel.Name!; + + /// + /// The channel topic, between 0 and 1024 characters. Can be . + /// public string? Topic => _jsonModel.Topic; + + /// + /// Whether the channel is age-restricted. + /// public bool Nsfw => _jsonModel.Nsfw.GetValueOrDefault(); + + /// + /// The number of seconds a user has to wait before sending another message, between 0 and 21600 (6 hours). + /// + /// + /// Bots, and users with the permission are unaffected. + /// public int Slowmode => _jsonModel.Slowmode.GetValueOrDefault(); + + /// + /// The ID of the channel's parent category. + /// public ulong? ParentId => _jsonModel.ParentId; + + /// + /// How long threads within the channel must be inactive, before auto-archiving occurs. + /// public ThreadArchiveDuration? DefaultAutoArchiveDuration => _jsonModel.DefaultAutoArchiveDuration; + + /// + /// The default slowmode duration for threads within the channel. + /// public int DefaultThreadSlowmode => _jsonModel.DefaultThreadSlowmode.GetValueOrDefault(); } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/AnnouncementGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/AnnouncementGuildThread.cs index a971a3f8f..3e32d3547 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/AnnouncementGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/AnnouncementGuildThread.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a thread within a . +/// public partial class AnnouncementGuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : GuildThread(jsonModel, client) { } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/ForumGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/ForumGuildThread.cs index cdc631cc0..2a237a7b0 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/ForumGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/ForumGuildThread.cs @@ -3,7 +3,13 @@ namespace NetCord; +/// +/// Represents a within a . +/// public partial class ForumGuildThread(JsonChannel jsonModel, RestClient client) : PublicGuildThread(jsonModel, client) { + /// + /// The message embedded as the thread's starting point. + /// public RestMessage Message { get; } = new(jsonModel.Message!, client); } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/GuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/GuildThread.cs index ae04a3fd1..22244d897 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/GuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/GuildThread.cs @@ -2,13 +2,47 @@ namespace NetCord; +/// +/// Represents a thread within a guild. +/// public abstract partial class GuildThread : TextGuildChannel { + /// + /// The ID of the this thread was created in. + /// + public new ulong? ParentId => base.ParentId; + + /// + /// The ID of the thread's creator. + /// public ulong OwnerId => _jsonModel.OwnerId.GetValueOrDefault(); + + /// + /// The number of messages within the thread, excluding the initial and deleted messages. + /// + /// + /// For threads created before July 1, 2022, the message count is inaccurate when greater than 50. + /// public int MessageCount => _jsonModel.MessageCount.GetValueOrDefault(); + + /// + /// An approximation of the number of users within the thread. Stops counting at 50 users. + /// public int UserCount => _jsonModel.UserCount.GetValueOrDefault(); + + /// + /// Additional metadata for the thread, unnecessary for standard channel operations. + /// public GuildThreadMetadata Metadata { get; } + + /// + /// A minimal for the current user, if they have joined the thread. + /// public ThreadCurrentUser? CurrentUser { get; } + + /// + /// The total number of messages sent in the thread, including deletions. + /// public int TotalMessageSent => _jsonModel.TotalMessageSent.GetValueOrDefault(); protected GuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : base(jsonModel, jsonModel.GuildId.GetValueOrDefault(), client) @@ -17,7 +51,7 @@ protected GuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : bas var jsonCurrentUser = jsonModel.CurrentUser; if (jsonCurrentUser is not null) - CurrentUser = new(jsonCurrentUser); + CurrentUser = new(jsonCurrentUser ); } public static new GuildThread CreateFromJson(JsonModels.JsonChannel jsonChannel, RestClient client) diff --git a/NetCord/Channels/TextChannels/Guild/Threads/GuildThreadMetadata.cs b/NetCord/Channels/TextChannels/Guild/Threads/GuildThreadMetadata.cs index 98f8b57fc..e5125d462 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/GuildThreadMetadata.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/GuildThreadMetadata.cs @@ -1,12 +1,48 @@ namespace NetCord; +/// +/// Contains additional metadata for threads, irrelevant for standard channels. +/// public class GuildThreadMetadata(JsonModels.JsonGuildThreadMetadata jsonModel) : IJsonModel { JsonModels.JsonGuildThreadMetadata IJsonModel.JsonModel => jsonModel; + /// + /// Whether the thread is currently archived. + /// public bool Archived => jsonModel.Archived; + + /// + /// How long the thread must be inactive before auto-archiving occurs. + /// public ThreadArchiveDuration AutoArchiveDuration => jsonModel.AutoArchiveDuration; + + /// + /// When the thread's activity status was last updated. + /// public DateTimeOffset ArchiveTimestamp => jsonModel.ArchiveTimestamp; + + /// + /// Whether the thread has been locked. + /// + /// + /// Locked threads can only be unlocked using the permission. + /// public bool Locked => jsonModel.Locked; + + /// + /// Whether non-moderators can add other non-moderators to a thread. + /// + /// + /// Only available for private threads. + /// public bool? Invitable => jsonModel.Invitable; + + /// + /// When the thread was initially created. + /// + /// + /// Only populated for threads created after 2022-01-09. + /// + public DateTimeOffset CreateTimestamp => jsonModel.CreateTimestamp.GetValueOrDefault(); } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/IUnknownGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/IUnknownGuildThread.cs index 551e598d5..800b264be 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/IUnknownGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/IUnknownGuildThread.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Represents a guild thread of an unresolved type. +/// public partial interface IUnknownGuildThread : IUnknownGuildChannel { } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/PrivateGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/PrivateGuildThread.cs index 3f4be6196..6fb11eddd 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/PrivateGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/PrivateGuildThread.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a only accessible to a subset of users. +/// public partial class PrivateGuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : GuildThread(jsonModel, client) { } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/PublicGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/PublicGuildThread.cs index 822c0200b..e14cf9079 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/PublicGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/PublicGuildThread.cs @@ -2,7 +2,16 @@ namespace NetCord; +/// +/// Represents a accessible to all users. +/// public partial class PublicGuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : GuildThread(jsonModel, client) { + /// + /// The set of tags applied to the thread. + /// + /// + /// Only available if the thread is within a or . + /// public IReadOnlyList? AppliedTags => _jsonModel.AppliedTags; } diff --git a/NetCord/Channels/TextChannels/Guild/Threads/UnknownGuildThread.cs b/NetCord/Channels/TextChannels/Guild/Threads/UnknownGuildThread.cs index 867f25a24..f8c64f108 100644 --- a/NetCord/Channels/TextChannels/Guild/Threads/UnknownGuildThread.cs +++ b/NetCord/Channels/TextChannels/Guild/Threads/UnknownGuildThread.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a guild thread of a unresolved type. +/// internal partial class UnknownGuildThread(JsonModels.JsonChannel jsonModel, RestClient client) : GuildThread(jsonModel, client), IUnknownGuildThread { public ChannelType Type => _jsonModel.Type; diff --git a/NetCord/ClipAttachment.cs b/NetCord/ClipAttachment.cs new file mode 100644 index 000000000..9b542e7f5 --- /dev/null +++ b/NetCord/ClipAttachment.cs @@ -0,0 +1,33 @@ +using NetCord.Rest; + +namespace NetCord; + +/// +/// Represents an with properties relevant to stream clips. +/// +public class ClipAttachment : Attachment +{ + public ClipAttachment(JsonModels.JsonAttachment jsonModel, RestClient client) : base(jsonModel) + { + ClipParticipants = jsonModel.ClipParticipants!.Select(p => new User(p, client)).ToArray(); + + var application = jsonModel.Application; + if (application is not null) + Application = new(application, client); + } + + /// + /// A list of users present in the stream clip. + /// + public IReadOnlyList ClipParticipants { get; } + + /// + /// When the clip was created. + /// + public DateTimeOffset ClipCreatedAt => _jsonModel.ClipCreatedAt.GetValueOrDefault(); + + /// + /// The application in the stream clip, if recognized. + /// + public Application? Application { get; } +} diff --git a/NetCord/CustomEmoji.cs b/NetCord/CustomEmoji.cs index caa9ee1d1..254fa2510 100644 --- a/NetCord/CustomEmoji.cs +++ b/NetCord/CustomEmoji.cs @@ -3,6 +3,9 @@ namespace NetCord; +/// +/// Represents a custom (user-uploaded) emoji. +/// public abstract class CustomEmoji : Emoji, ISpanFormattable { private protected RestClient _client; @@ -16,16 +19,34 @@ public CustomEmoji(JsonEmoji jsonModel, RestClient client) : base(jsonModel) Creator = new(creator, client); } + /// + /// The emoji's unique ID. + /// public ulong Id => _jsonModel.Id.GetValueOrDefault(); + /// + /// The user that uploaded the emoji. + /// public User? Creator { get; } + /// + /// Whether this emoji must be wrapped in colons. + /// public bool? RequireColons => _jsonModel.RequireColons; + /// + /// Whether the emoji is managed. + /// public bool? Managed => _jsonModel.Managed; + /// + /// Whether the emoji is available for use. Can be if server boosts are lost. + /// public bool? Available => _jsonModel.Available; + /// + /// Returns an image representation of the emoji. + /// public ImageUrl GetImageUrl(ImageFormat format) => ImageUrl.CustomEmoji(Id, format); public override string ToString() => Animated ? $"" : $"<:{Name}:{Id}>"; diff --git a/NetCord/EmbedAuthor.cs b/NetCord/EmbedAuthor.cs index 0cee5f15e..4dc92b4ba 100644 --- a/NetCord/EmbedAuthor.cs +++ b/NetCord/EmbedAuthor.cs @@ -8,17 +8,17 @@ public class EmbedAuthor(JsonModels.JsonEmbedAuthor jsonModel) : IJsonModel.JsonModel => jsonModel; /// - /// The name of the author, displayed next to the icon if one is specified in . + /// The name of the author, displayed next to the icon if one is specified. /// public string? Name => jsonModel.Name; /// - /// When set, turns the into a clickable link, pointing to the specified URL. + /// When set, turns the name into a clickable link, pointing to the specified URL. /// public string? Url => jsonModel.Url; /// - /// Points to an image, which is displayed in a small circular format to the left of the . + /// Points to an image, which is displayed in a small circular format to the left of the name. /// public string? IconUrl => jsonModel.IconUrl; diff --git a/NetCord/EmbedField.cs b/NetCord/EmbedField.cs index 2b562d4df..6f0e258d4 100644 --- a/NetCord/EmbedField.cs +++ b/NetCord/EmbedField.cs @@ -18,7 +18,7 @@ public class EmbedField(JsonModels.JsonEmbedField jsonModel) : IJsonModel jsonModel.Value; /// - /// When set alongside another field with set, displays the fields side by side. + /// When set alongside another field with set, displays the fields side by side when supported. /// public bool Inline => jsonModel.Inline; } diff --git a/NetCord/Emoji.cs b/NetCord/Emoji.cs index d29dc806d..7377608b5 100644 --- a/NetCord/Emoji.cs +++ b/NetCord/Emoji.cs @@ -3,14 +3,23 @@ namespace NetCord; +/// +/// Represents a standard Discord emoji. +/// public class Emoji : IJsonModel { JsonEmoji IJsonModel.JsonModel => _jsonModel; private protected readonly JsonEmoji _jsonModel; + /// + /// The emoji's name. + /// public string Name => _jsonModel.Name!; + /// + /// Whether the emoji is animated. + /// public bool Animated => _jsonModel.Animated; private protected Emoji(JsonEmoji jsonModel) diff --git a/NetCord/EmojiReference.cs b/NetCord/EmojiReference.cs index a29243a13..de87e8b65 100644 --- a/NetCord/EmojiReference.cs +++ b/NetCord/EmojiReference.cs @@ -1,12 +1,18 @@ namespace NetCord; +/// +/// Represents a lightweight reference to an emoji. +/// public class EmojiReference(JsonModels.JsonEmoji jsonModel) : IJsonModel { JsonModels.JsonEmoji IJsonModel.JsonModel => jsonModel; + /// public ulong? Id => jsonModel.Id; + /// public string Name => jsonModel.Name!; + /// public bool Animated => jsonModel.Animated; } diff --git a/NetCord/ForumGuildChannelDefaultReaction.cs b/NetCord/ForumGuildChannelDefaultReaction.cs index 2718e93c7..c9d320ca6 100644 --- a/NetCord/ForumGuildChannelDefaultReaction.cs +++ b/NetCord/ForumGuildChannelDefaultReaction.cs @@ -2,10 +2,26 @@ namespace NetCord; +/// +/// Represents the default displayed reaction for threads within a or . +/// public class ForumGuildChannelDefaultReaction(JsonForumGuildChannelDefaultReaction jsonModel) : IJsonModel { JsonForumGuildChannelDefaultReaction IJsonModel.JsonModel => jsonModel; + /// + /// The ID of the custom guild emoji to use for the reaction. + /// + /// + /// Cannot be set alongside . + /// public ulong? EmojiId => jsonModel.EmojiId; + + /// + /// The unicode emoji to use for the reaction. + /// + /// + /// Cannot be set alongside . + /// public string? EmojiName => jsonModel.EmojiName; } diff --git a/NetCord/ForumLayoutType.cs b/NetCord/ForumLayoutType.cs index 039566f00..cfc87aef2 100644 --- a/NetCord/ForumLayoutType.cs +++ b/NetCord/ForumLayoutType.cs @@ -1,8 +1,22 @@ namespace NetCord; +/// +/// Determines the visual post layout of a . +/// public enum ForumLayoutType { + /// + /// No default post layout set. + /// NotSet = 0, + + /// + /// Posts are displayed as a sequential list. + /// ListView = 1, + + /// + /// Posts are displayed as a collection of tiles. + /// GalleryView = 2, } diff --git a/NetCord/ForumTag.cs b/NetCord/ForumTag.cs index ae654c7cf..dcc678971 100644 --- a/NetCord/ForumTag.cs +++ b/NetCord/ForumTag.cs @@ -2,13 +2,41 @@ namespace NetCord; +/// +/// Represents a tag that can be applied to a . +/// public class ForumTag(JsonForumTag jsonModel) : Entity, IJsonModel { JsonForumTag IJsonModel.JsonModel => jsonModel; + /// + /// The ID of the tag. + /// public override ulong Id => jsonModel.Id; + + /// + /// The name of the tag, between 0 and 20 characters. + /// public string Name => jsonModel.Name; + + /// + /// Whether this tag can only be added/removed using the permission. + /// public bool Moderated => jsonModel.Moderated; + + /// + /// The ID of the custom guild emoji to use for the tag. + /// + /// + /// Cannot be set alongside . + /// public ulong? EmojiId => jsonModel.EmojiId; + + /// + /// The unicode emoji to use for the tag. + /// + /// + /// Cannot be set alongside . + /// public string? EmojiName => jsonModel.EmojiName; } diff --git a/NetCord/GuildChannelMention.cs b/NetCord/GuildChannelMention.cs index dc2a44155..45a1a877d 100644 --- a/NetCord/GuildChannelMention.cs +++ b/NetCord/GuildChannelMention.cs @@ -1,9 +1,27 @@ namespace NetCord; +/// +/// Represents a mentioned channel (such as <#1060153373401288816>). +/// public class GuildChannelMention(JsonModels.JsonGuildChannelMention jsonModel) : Entity { + /// + /// The guild channel's ID. + /// public override ulong Id => jsonModel.Id; + + /// + /// The containing guild's ID. + /// public ulong GuildId => jsonModel.GuildId; + + /// + /// The guild channel's type. + /// public ChannelType Type => jsonModel.Type; + + /// + /// The guild channel's name. + /// public string Name => jsonModel.Name; } diff --git a/NetCord/GuildEmoji.cs b/NetCord/GuildEmoji.cs index 6207fe81b..566ed648a 100644 --- a/NetCord/GuildEmoji.cs +++ b/NetCord/GuildEmoji.cs @@ -3,9 +3,18 @@ namespace NetCord; +/// +/// Represents a custom guild emoji. +/// public partial class GuildEmoji(JsonEmoji jsonModel, ulong guildId, RestClient client) : CustomEmoji(jsonModel, client) { + /// + /// A list of roles allowed to use this emoji. + /// public IReadOnlyList? AllowedRoles => _jsonModel.AllowedRoles; + /// + /// The ID corresponding to the emoji's parent guild. + /// public ulong GuildId { get; } = guildId; } diff --git a/NetCord/GuildSticker.cs b/NetCord/GuildSticker.cs index 9e5037717..d30820b87 100644 --- a/NetCord/GuildSticker.cs +++ b/NetCord/GuildSticker.cs @@ -2,14 +2,26 @@ namespace NetCord; +/// +/// Represents a custom guild sticker. +/// public partial class GuildSticker : Sticker { private readonly RestClient _client; + /// + /// Whether the sticker is available for use. Can be if server boosts are lost. + /// public bool? Available => _jsonModel.Available; + /// + /// The ID corresponding to the sticker's parent guild. + /// public ulong GuildId => _jsonModel.GuildId; + /// + /// The user that uploaded the sticker. + /// public User? Creator { get; } public GuildSticker(JsonModels.JsonSticker jsonModel, RestClient client) : base(jsonModel) diff --git a/NetCord/GuildUser.cs b/NetCord/GuildUser.cs index 5d7744f77..953fc14db 100644 --- a/NetCord/GuildUser.cs +++ b/NetCord/GuildUser.cs @@ -16,14 +16,14 @@ public partial class GuildUser(JsonGuildUser jsonModel, ulong guildId, RestClien /// /// Gets the of the user's guild avatar. /// - /// The format of the returned . Defaults to (or for animated avatars). + /// The format of the returned . Defaults to (or for animated avatars). /// An pointing to the user's guild avatar. If the user does not have one set, returns . public ImageUrl? GetGuildAvatarUrl(ImageFormat? format = null) => GuildAvatarHash is string hash ? ImageUrl.GuildUserAvatar(guildId, Id, hash, format) : null; /// /// Gets the of the user's guild banner. /// - /// The format of the returned . Defaults to (or for animated banners). + /// The format of the returned . Defaults to (or for animated banners). /// An pointing to the user's guild banner. If the user does not have one set, returns . public ImageUrl? GetGuildBannerUrl(ImageFormat? format = null) => GuildBannerHash is string hash ? ImageUrl.GuildUserBanner(guildId, Id, hash, format) : null; diff --git a/NetCord/ImageAttachment.cs b/NetCord/ImageAttachment.cs index a4651724f..43e711027 100644 --- a/NetCord/ImageAttachment.cs +++ b/NetCord/ImageAttachment.cs @@ -1,14 +1,29 @@ +using NetCord.Rest; + namespace NetCord; +/// +/// Represents an with properties relevant to image/video files. +/// public class ImageAttachment(JsonModels.JsonAttachment jsonModel) : Attachment(jsonModel) { /// - /// Height of file. + /// The height of the attachment in pixels. /// public int Height => _jsonModel.Height.GetValueOrDefault(); /// - /// Width of file. + /// The width of the attachment in pixels. /// public int Width => _jsonModel.Width.GetValueOrDefault(); + + /// + /// The attachment's thumbhash placeholder. + /// + public string? Placeholder => _jsonModel.Placeholder; + + /// + /// The 's version. + /// + public int PlaceholderVersion => _jsonModel.PlaceholderVersion.GetValueOrDefault(); } diff --git a/NetCord/ImageFormat.cs b/NetCord/ImageFormat.cs index 90df022ca..a9de47f98 100644 --- a/NetCord/ImageFormat.cs +++ b/NetCord/ImageFormat.cs @@ -1,10 +1,32 @@ namespace NetCord; +/// +/// Specifies the format of an image. +/// public enum ImageFormat : byte { - Jpeg, - Png, + /// + /// An image in the JPEG format. + /// + JPEG, + + /// + /// An image in the PNG format. + /// + PNG, + + /// + /// An image in the WebP format, potentially animated. + /// WebP, - Gif, + + /// + /// An animated image in the GIF format. + /// + GIF, + + /// + /// An animated image in the Lottie format. Rarely available. + /// Lottie, } diff --git a/NetCord/ImageUrl.cs b/NetCord/ImageUrl.cs index 03f8e9112..2fde76bfb 100644 --- a/NetCord/ImageUrl.cs +++ b/NetCord/ImageUrl.cs @@ -146,10 +146,10 @@ internal static string GetFormat(ImageFormat format) { return format switch { - ImageFormat.Jpeg => "jpg", - ImageFormat.Png => "png", + ImageFormat.JPEG => "jpg", + ImageFormat.PNG => "png", ImageFormat.WebP => "webp", - ImageFormat.Gif => "gif", + ImageFormat.GIF => "gif", ImageFormat.Lottie => "json", _ => throw new System.ComponentModel.InvalidEnumArgumentException("Invalid image format.") }; @@ -159,10 +159,10 @@ internal static ReadOnlySpan GetFormatBytes(ImageFormat format) { return format switch { - ImageFormat.Jpeg => "jpg"u8, - ImageFormat.Png => "png"u8, + ImageFormat.JPEG => "jpg"u8, + ImageFormat.PNG => "png"u8, ImageFormat.WebP => "webp"u8, - ImageFormat.Gif => "gif"u8, + ImageFormat.GIF => "gif"u8, ImageFormat.Lottie => "json"u8, _ => throw new System.ComponentModel.InvalidEnumArgumentException("Invalid image format.") }; @@ -184,7 +184,7 @@ public static ImageUrl CustomEmoji(ulong emojiId, ImageFormat format) /// /// The ID of the guild. /// The guild's icon hash. - /// The format of the returned . Defaults to (or for animated icons). + /// The format of the returned . Defaults to (or for animated icons). /// An pointing to the guild's icon. public static ImageUrl GuildIcon(ulong guildId, string iconHash, ImageFormat? format) { @@ -220,7 +220,7 @@ public static ImageUrl GuildDiscoverySplash(ulong guildId, string discoverySplas /// /// The ID of the guild. /// The guild's banner hash. - /// The format of the returned . Defaults to (or for animated banners). + /// The format of the returned . Defaults to (or for animated banners). /// An pointing to the guild's banner. public static ImageUrl GuildBanner(ulong guildId, string bannerHash, ImageFormat? format) { @@ -232,7 +232,7 @@ public static ImageUrl GuildBanner(ulong guildId, string bannerHash, ImageFormat /// /// The ID of the user. /// The user's banner hash. - /// The format of the returned . Defaults to (or for animated banners). + /// The format of the returned . Defaults to (or for animated banners). /// An pointing to the user's banner. public static ImageUrl UserBanner(ulong userId, string bannerHash, ImageFormat? format) { @@ -270,7 +270,7 @@ public static ImageUrl DefaultUserAvatar(ulong id) /// /// The ID of the user. /// The user's avatar hash. - /// The format of the returned . Defaults to (or for animated avatars). + /// The format of the returned . Defaults to (or for animated avatars). /// An pointing to the user's avatar. public static ImageUrl UserAvatar(ulong userId, string avatarHash, ImageFormat? format) { @@ -283,7 +283,7 @@ public static ImageUrl UserAvatar(ulong userId, string avatarHash, ImageFormat? /// The ID of the guild. /// The ID of the user. /// The user's avatar hash. - /// The format of the returned . Defaults to (or for animated avatars). + /// The format of the returned . Defaults to (or for animated avatars). /// An pointing to the guild user's avatar. public static ImageUrl GuildUserAvatar(ulong guildId, ulong userId, string avatarHash, ImageFormat? format) { @@ -396,7 +396,7 @@ public static ImageUrl TeamIcon(ulong teamId, string iconHash, ImageFormat forma /// public static ImageUrl Sticker(ulong stickerId, StickerFormat stickerFormat, ImageFormat format) { - return new($"/stickers/{stickerId}", GetFormat(format), stickerFormat is StickerFormat.Gif ? Discord.MediaUrl : Discord.CDNUrl, false); + return new($"/stickers/{stickerId}", GetFormat(format), stickerFormat is StickerFormat.GIF ? Discord.MediaUrl : Discord.CDNUrl, false); } /// @@ -429,7 +429,7 @@ public static ImageUrl GuildScheduledEventCover(ulong scheduledEventId, string c /// The ID of the guild. /// The ID of the user. /// The user's banner hash. - /// The format of the returned . Defaults to (or for animated banners). + /// The format of the returned . Defaults to (or for animated banners). /// An pointing to the guild user's banner. public static ImageUrl GuildUserBanner(ulong guildId, ulong userId, string bannerHash, ImageFormat? format) { diff --git a/NetCord/InteractionResolvedData.cs b/NetCord/InteractionResolvedData.cs index eb03332c6..b4fa4d58b 100644 --- a/NetCord/InteractionResolvedData.cs +++ b/NetCord/InteractionResolvedData.cs @@ -3,16 +3,34 @@ namespace NetCord; +/// +/// Contains resolved information for an interaction's auto-populated selection menus. +/// public class InteractionResolvedData { + /// + /// A list of user objects, mapped to their IDs. + /// public IReadOnlyDictionary? Users { get; } + /// + /// A list of role objects, mapped to their IDs. + /// public IReadOnlyDictionary? Roles { get; } + /// + /// A list of channel objects, mapped to their IDs. + /// public IReadOnlyDictionary? Channels { get; } + /// + /// A list of message objects, mapped to their IDs. + /// public IReadOnlyDictionary? Messages { get; } + /// + /// A list of attachment objects, mapped to their IDs. + /// public IReadOnlyDictionary? Attachments { get; } public InteractionResolvedData(JsonInteractionResolvedData jsonModel, ulong? guildId, RestClient client) @@ -65,6 +83,6 @@ public InteractionResolvedData(JsonInteractionResolvedData jsonModel, ulong? gui var attachments = jsonModel.Attachments; if (attachments is not null) - Attachments = attachments.ToDictionary(c => c.Key, c => Attachment.CreateFromJson(c.Value)); + Attachments = attachments.ToDictionary(c => c.Key, c => Attachment.CreateFromJson(c.Value, client)); } } diff --git a/NetCord/JsonModels/JsonAttachment.cs b/NetCord/JsonModels/JsonAttachment.cs index 04d3a4c80..28f789cd7 100644 --- a/NetCord/JsonModels/JsonAttachment.cs +++ b/NetCord/JsonModels/JsonAttachment.cs @@ -31,6 +31,12 @@ public class JsonAttachment : JsonEntity [JsonPropertyName("width")] public int? Width { get; set; } + [JsonPropertyName("placeholder")] + public string? Placeholder; + + [JsonPropertyName("placeholder_version")] + public int? PlaceholderVersion { get; set; } + [JsonPropertyName("ephemeral")] public bool Ephemeral { get; set; } @@ -42,4 +48,13 @@ public class JsonAttachment : JsonEntity [JsonPropertyName("flags")] public AttachmentFlags Flags { get; set; } + + [JsonPropertyName("clip_participants")] + public JsonUser[]? ClipParticipants { get; set; } + + [JsonPropertyName("clip_created_at")] + public DateTimeOffset? ClipCreatedAt { get; set; } + + [JsonPropertyName("application")] + public JsonApplication? Application { get; set; } } diff --git a/NetCord/JsonModels/JsonGuildThreadMetadata.cs b/NetCord/JsonModels/JsonGuildThreadMetadata.cs index dd6493c71..30e9c2500 100644 --- a/NetCord/JsonModels/JsonGuildThreadMetadata.cs +++ b/NetCord/JsonModels/JsonGuildThreadMetadata.cs @@ -18,4 +18,7 @@ public class JsonGuildThreadMetadata [JsonPropertyName("invitable")] public bool? Invitable { get; set; } + + [JsonPropertyName("create_timestamp")] + public DateTimeOffset? CreateTimestamp { get; set; } } diff --git a/NetCord/JsonModels/JsonMessage.cs b/NetCord/JsonModels/JsonMessage.cs index ddffd783e..90592e2e9 100644 --- a/NetCord/JsonModels/JsonMessage.cs +++ b/NetCord/JsonModels/JsonMessage.cs @@ -113,4 +113,7 @@ public class JsonMessage : JsonEntity [JsonPropertyName("call")] public JsonMessageCall? Call { get; set; } + + [JsonPropertyName("shared_client_theme")] + public JsonSharedClientTheme? SharedClientTheme { get; set; } } diff --git a/NetCord/JsonModels/JsonSharedClientTheme.cs b/NetCord/JsonModels/JsonSharedClientTheme.cs new file mode 100644 index 000000000..af925350d --- /dev/null +++ b/NetCord/JsonModels/JsonSharedClientTheme.cs @@ -0,0 +1,18 @@ +using System.Text.Json.Serialization; + +namespace NetCord.JsonModels; + +public class JsonSharedClientTheme +{ + [JsonPropertyName("colors")] + public Color[] Colors { get; set; } + + [JsonPropertyName("gradient_angle")] + public int GradientAngle { get; set; } + + [JsonPropertyName("base_mix")] + public int BaseMix { get; set; } + + [JsonPropertyName("base_theme")] + public BaseTheme? BaseTheme { get; set; } +} diff --git a/NetCord/MessageFlags.cs b/NetCord/MessageFlags.cs index 7ae5ef770..ce8ebd5c0 100644 --- a/NetCord/MessageFlags.cs +++ b/NetCord/MessageFlags.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Contains additional information about a message's state. +/// [Flags] public enum MessageFlags : uint { diff --git a/NetCord/MessagePoll.cs b/NetCord/MessagePoll.cs index f0aa05e37..a808a6403 100644 --- a/NetCord/MessagePoll.cs +++ b/NetCord/MessagePoll.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a poll within a message. +/// public class MessagePoll : IJsonModel { JsonMessagePoll IJsonModel.JsonModel => _jsonModel; @@ -19,10 +22,33 @@ public MessagePoll(JsonMessagePoll jsonModel) Results = new(results); } + /// + /// The question displayed in the poll. + /// public MessagePollMedia Question { get; } + + /// + /// The set of answers available in the poll. + /// public IReadOnlyList Answers { get; } + + /// + /// A timestamp specifying the poll's expiry date. + /// public DateTimeOffset? ExpiresAt => _jsonModel.ExpiresAt; + + /// + /// Whether a user can submit multiple answers to the poll. + /// public bool AllowMultiselect => _jsonModel.AllowMultiselect; + + /// + /// The poll's displayed layout type. + /// public MessagePollLayoutType LayoutType => _jsonModel.LayoutType; + + /// + /// The poll's results. + /// public MessagePollResults? Results { get; } } diff --git a/NetCord/MessagePollAnswer.cs b/NetCord/MessagePollAnswer.cs index 6462261f3..6dce84d1c 100644 --- a/NetCord/MessagePollAnswer.cs +++ b/NetCord/MessagePollAnswer.cs @@ -2,10 +2,21 @@ namespace NetCord; +/// +/// Represents an answer choice within a poll. +/// +/// public class MessagePollAnswer(JsonMessagePollAnswer jsonModel) : IJsonModel { JsonMessagePollAnswer IJsonModel.JsonModel => jsonModel; + /// + /// The answer's ID. + /// public int AnswerId => jsonModel.AnswerId; + + /// + /// The answer's displayed contents. + /// public MessagePollMedia PollMedia { get; } = new(jsonModel.PollMedia); } diff --git a/NetCord/MessagePollAnswerCount.cs b/NetCord/MessagePollAnswerCount.cs index c49e345d2..8d962444d 100644 --- a/NetCord/MessagePollAnswerCount.cs +++ b/NetCord/MessagePollAnswerCount.cs @@ -2,11 +2,25 @@ namespace NetCord; +/// +/// Represents a count of votes for a poll answer. +/// public class MessagePollAnswerCount(JsonMessagePollAnswerCount jsonModel) : IJsonModel { JsonMessagePollAnswerCount IJsonModel.JsonModel => jsonModel; + /// + /// The ID of the count's corresponding answer. + /// public int AnswerId => jsonModel.AnswerId; + + /// + /// The count of votes for the answer. + /// public int Count => jsonModel.Count; + + /// + /// Whether the current user has also voted for the answer. + /// public bool MeVoted => jsonModel.MeVoted; } diff --git a/NetCord/MessagePollLayoutType.cs b/NetCord/MessagePollLayoutType.cs index fbe37a5ac..52a980780 100644 --- a/NetCord/MessagePollLayoutType.cs +++ b/NetCord/MessagePollLayoutType.cs @@ -1,6 +1,12 @@ namespace NetCord; +/// +/// Specifies a poll's displayed layout type. +/// public enum MessagePollLayoutType : byte { + /// + /// The default poll layout. + /// Default = 1, } diff --git a/NetCord/MessagePollMedia.cs b/NetCord/MessagePollMedia.cs index 0f6b862fb..e54c12f38 100644 --- a/NetCord/MessagePollMedia.cs +++ b/NetCord/MessagePollMedia.cs @@ -2,12 +2,22 @@ namespace NetCord; +/// +/// Represents the media displayed within a poll. +/// public class MessagePollMedia : IJsonModel { JsonMessagePollMedia IJsonModel.JsonModel => _jsonModel; private readonly JsonMessagePollMedia _jsonModel; + /// + /// The text to display in the poll, up to 300 characters. + /// public string? Text => _jsonModel.Text; + + /// + /// The emoji to display in the poll. Only supported for answers. + /// public EmojiReference? Emoji { get; } public MessagePollMedia(JsonMessagePollMedia jsonModel) diff --git a/NetCord/MessagePollResults.cs b/NetCord/MessagePollResults.cs index 75dfd0159..f581251da 100644 --- a/NetCord/MessagePollResults.cs +++ b/NetCord/MessagePollResults.cs @@ -2,10 +2,21 @@ namespace NetCord; +/// +/// Represents the results of a poll. +/// +/// public class MessagePollResults(JsonMessagePollResults jsonModel) : IJsonModel { JsonMessagePollResults IJsonModel.JsonModel => jsonModel; + /// + /// If , the counts provided in are accurately tallied, otherwise small deviations can occur. + /// public bool IsFinalized => jsonModel.IsFinalized; + + /// + /// A list of vote counts for each answer. If an answer is not included, it held no votes. + /// public IReadOnlyList Answers { get; } = jsonModel.Answers.Select(x => new MessagePollAnswerCount(x)).ToArray(); } diff --git a/NetCord/MessageReaction.cs b/NetCord/MessageReaction.cs index b6be65a81..7688b4541 100644 --- a/NetCord/MessageReaction.cs +++ b/NetCord/MessageReaction.cs @@ -1,18 +1,39 @@ namespace NetCord; +/// +/// Represents a reaction to a message. +/// public class MessageReaction(JsonModels.JsonMessageReaction jsonModel) : IJsonModel { JsonModels.JsonMessageReaction IJsonModel.JsonModel => jsonModel; + /// + /// The total number of times this reaction has been applied, including super reactions. + /// public int Count => jsonModel.Count; + /// + /// Contains additional information on the reaction count. + /// public MessageReactionCountDetails CountDetails { get; } = new(jsonModel.CountDetails); + /// + /// Whether the current user applied this reaction. + /// public bool Me => jsonModel.Me; + /// + /// Whether the current user applied this reaction as a super reaction. + /// public bool MeBurst => jsonModel.MeBurst; + /// + /// A minimal emoji object, containing information about the reacted emoji. + /// public MessageReactionEmoji Emoji { get; } = new(jsonModel.Emoji); + /// + /// An array of colors used for super reactions. + /// public IReadOnlyList BurstColors => jsonModel.BurstColors; } diff --git a/NetCord/MessageReactionCountDetails.cs b/NetCord/MessageReactionCountDetails.cs index fc9add1d6..fe8629292 100644 --- a/NetCord/MessageReactionCountDetails.cs +++ b/NetCord/MessageReactionCountDetails.cs @@ -1,16 +1,19 @@ namespace NetCord; +/// +/// Represents count information for a object. +/// public class MessageReactionCountDetails(JsonModels.JsonMessageReactionCountDetails jsonModel) : IJsonModel { JsonModels.JsonMessageReactionCountDetails IJsonModel.JsonModel => jsonModel; /// - /// Count of super reactions. + /// The number of applied ssuper reactions. /// public int Burst => jsonModel.Burst; /// - /// Count of normal reactions. + /// The number of applied normal reactions. /// public int Normal => jsonModel.Normal; } diff --git a/NetCord/MessageReactionEmoji.cs b/NetCord/MessageReactionEmoji.cs index fd68fbb31..129c179d5 100644 --- a/NetCord/MessageReactionEmoji.cs +++ b/NetCord/MessageReactionEmoji.cs @@ -1,12 +1,24 @@ namespace NetCord; +/// +/// Contains information about a 's emoji. +/// public class MessageReactionEmoji(JsonModels.JsonEmoji jsonModel) : IJsonModel { JsonModels.JsonEmoji IJsonModel.JsonModel => jsonModel; + /// + /// Can be for standard emoji. + /// public ulong? Id => jsonModel.Id; + /// + /// The emoji's name. + /// public string? Name => jsonModel.Name; + /// + /// Whether the emoji is animated. + /// public bool Animated => jsonModel.Animated; } diff --git a/NetCord/MessageSnapshotMessage.cs b/NetCord/MessageSnapshotMessage.cs index 51242ff43..f2f1047c2 100644 --- a/NetCord/MessageSnapshotMessage.cs +++ b/NetCord/MessageSnapshotMessage.cs @@ -25,7 +25,7 @@ public class MessageSnapshotMessage(JsonMessageSnapshotMessage jsonModel, ulong? /// /// A list of objects indexed by their IDs, containing any files attached in the message. /// - public IReadOnlyList Attachments { get; } = jsonModel.Attachments.Select(Attachment.CreateFromJson).ToArray(); + public IReadOnlyList Attachments { get; } = jsonModel.Attachments.Select(a => Attachment.CreateFromJson(a, client)).ToArray(); /// /// When the message was edited (or null if never). diff --git a/NetCord/MessageSticker.cs b/NetCord/MessageSticker.cs index 4b638b62c..5d3555d65 100644 --- a/NetCord/MessageSticker.cs +++ b/NetCord/MessageSticker.cs @@ -2,13 +2,19 @@ namespace NetCord; +/// +/// Represents a sticker sent within a message object. +/// public class MessageSticker(JsonModels.JsonMessageSticker jsonModel, RestClient client) : ClientEntity(client), IJsonModel { JsonModels.JsonMessageSticker IJsonModel.JsonModel => jsonModel; + /// public override ulong Id => jsonModel.Id; + /// public string Name => jsonModel.Name; + /// public StickerFormat Format => jsonModel.Format; } diff --git a/NetCord/MessageType.cs b/NetCord/MessageType.cs index 7a99b4f98..7759105f0 100644 --- a/NetCord/MessageType.cs +++ b/NetCord/MessageType.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Specifies additional type information for a message object. +/// public enum MessageType { /// @@ -120,6 +123,9 @@ public enum MessageType /// /// Sent when an automod action is taken. /// + /// + /// Messages of this type can only be deleted using the permission. + /// AutoModerationAction = 24, /// diff --git a/NetCord/PermissionOverwrite.cs b/NetCord/PermissionOverwrite.cs index 11280e369..71d737828 100644 --- a/NetCord/PermissionOverwrite.cs +++ b/NetCord/PermissionOverwrite.cs @@ -1,14 +1,29 @@ namespace NetCord; +/// +/// Represents the set of permission overwrites for a given user/role ID. +/// public class PermissionOverwrite(JsonModels.JsonPermissionOverwrite jsonModel) : Entity, IJsonModel { JsonModels.JsonPermissionOverwrite IJsonModel.JsonModel => jsonModel; + /// + /// The ID of the user/role affected by this overwrite. + /// public override ulong Id => jsonModel.Id; + /// + /// Specifies whether the overwrite applies to a user, or a role. + /// public PermissionOverwriteType Type => jsonModel.Type; + /// + /// The set of permissions to grant the overwrite target. + /// public Permissions Allowed => jsonModel.Allowed; + /// + /// The set of permissions to deny the overwrite target. + /// public Permissions Denied => jsonModel.Denied; } diff --git a/NetCord/PermissionOverwriteType.cs b/NetCord/PermissionOverwriteType.cs index 45485d5c0..3045eb362 100644 --- a/NetCord/PermissionOverwriteType.cs +++ b/NetCord/PermissionOverwriteType.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Specifies whether a applies to a user, or role. +/// public enum PermissionOverwriteType { Role = 0, diff --git a/NetCord/Permissions.cs b/NetCord/Permissions.cs index 64db75813..daea4f5ca 100644 --- a/NetCord/Permissions.cs +++ b/NetCord/Permissions.cs @@ -1,5 +1,12 @@ namespace NetCord; +/// +/// Permissions are a way to limit and grant certain abilities to users in Discord. A set of base permissions can be configured at the guild level for different roles. +/// When these roles are attached to users, they grant or revoke specific privileges within the guild. +/// +/// +/// Along with the guild-level permissions, Discord also supports permission overwrites via that can be assigned to individual roles or members on a per-channel basis. +/// [Flags] public enum Permissions : ulong { @@ -11,26 +18,41 @@ public enum Permissions : ulong /// /// Allows kicking guild users. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// KickUsers = 1uL << 1, /// /// Allows banning guild users. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// BanUsers = 1uL << 2, /// /// Allows all permissions and bypasses channel permission overwrites. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// Administrator = 1uL << 3, /// /// Allows management and editing of channels. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageChannels = 1uL << 4, /// /// Allows management and editing of the guild. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageGuild = 1uL << 5, /// @@ -71,6 +93,9 @@ public enum Permissions : ulong /// /// Allows for deletion of other users messages. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageMessages = 1uL << 13, /// @@ -146,16 +171,25 @@ public enum Permissions : ulong /// /// Allows management and editing of roles. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageRoles = 1uL << 28, /// /// Allows management and editing of webhooks. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageWebhooks = 1uL << 29, /// /// Allows for editing and deleting emojis, stickers, and soundboard sounds created by all users. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageGuildExpressions = 1uL << 30, /// @@ -176,6 +210,9 @@ public enum Permissions : ulong /// /// Allows for deleting and archiving threads, and viewing all private threads. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ManageThreads = 1uL << 34, /// @@ -211,6 +248,9 @@ public enum Permissions : ulong /// /// Allows for viewing role subscription insights. /// + /// + /// For applications, owners must have 2FA enabled if server-wide 2FA is enabled. + /// ViewCreatorMonetizationAnalytics = 1uL << 41, /// @@ -238,14 +278,23 @@ public enum Permissions : ulong /// SendVoiceMessages = 1uL << 46, + /// + /// Allows setting voice channel status. + /// + SetVoiceChannelStatus = 1uL << 48, + /// /// Allows sending polls. /// SendPolls = 1uL << 49, /// - /// Allows user-installed apps to send public responses. When disabled, users will still be allowed to use their apps but the responses will be ephemeral. This only applies to apps not also installed to the server. + /// Allows user-installed apps to send public responses. /// + /// + /// When disabled, users will still be allowed to use their apps but the responses will be ephemeral. + /// This only applies to apps not also installed to the server. + /// UseExternalApplications = 1uL << 50, /// diff --git a/NetCord/Rest/AllowedMentionsProperties.cs b/NetCord/Rest/AllowedMentionsProperties.cs index 8dac8423f..75a4d5aa8 100644 --- a/NetCord/Rest/AllowedMentionsProperties.cs +++ b/NetCord/Rest/AllowedMentionsProperties.cs @@ -3,6 +3,9 @@ namespace NetCord.Rest; +/// +/// Defines which users and roles a message is allowed to mention. +/// [JsonConverter(typeof(AllowedMentionsConverter))] [GenerateMethodsForProperties] public partial class AllowedMentionsProperties @@ -10,28 +13,42 @@ public partial class AllowedMentionsProperties /// /// Allows and . /// + /// + /// The permission is required for this. + /// public bool Everyone { get; set; } = true; /// - /// Allowed roles, for all. + /// A list of mentionable role IDs. Allows all roles if set to . /// + /// /// + /// + /// If a role's property is set to , and is not set, it will not be mentioned regardless. + /// + /// public IEnumerable? AllowedRoles { get; set; } /// - /// Allowed users, for all. + /// A list of mentionable users. Allows all users if set to . /// public IEnumerable? AllowedUsers { get; set; } /// - /// Allows reply mention. + /// Allows mentioning the author of a replied-to message. /// public bool ReplyMention { get; set; } + /// + /// Gets an instance of with all mentions allowed. + /// public static AllowedMentionsProperties All => new() { ReplyMention = true, }; + /// + /// Gets an instance of with no mentions allowed. + /// public static AllowedMentionsProperties None { get diff --git a/NetCord/Rest/AttachmentProperties.cs b/NetCord/Rest/AttachmentProperties.cs index e010d7edb..4fbe4d2f9 100644 --- a/NetCord/Rest/AttachmentProperties.cs +++ b/NetCord/Rest/AttachmentProperties.cs @@ -4,6 +4,7 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class AttachmentProperties : IHttpSerializable, IJsonSerializable { @@ -13,37 +14,31 @@ public partial class AttachmentProperties : IHttpSerializable, IJsonSerializable private static readonly JsonEncodedText _description = JsonEncodedText.Encode("description"); /// - /// + /// Creates an attachment from the provided stream, with the given filename. /// - /// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). - /// Content of the file. + /// + /// A stream containing the attachment's contents. public AttachmentProperties(string fileName, Stream stream) : this(fileName) { _stream = stream; } /// - /// + /// Creates an empty attachment with the given filename. /// - /// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). + /// protected AttachmentProperties(string fileName) { FileName = fileName; } - /// - /// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). - /// + /// public string FileName { get; set; } - /// - /// Title of the attachment. - /// + /// public string? Title { get; set; } - /// - /// Description for the file (max 1024 characters for attachments sent by message, max 200 characters for attachments used for sticker creation). - /// + /// public string? Description { get; set; } protected Stream? GetStream() @@ -96,10 +91,10 @@ protected internal virtual void WriteTo(Utf8JsonWriter writer, int attachmentId) } /// -/// +/// Represents an attachment with Base64 encoded contents. /// -/// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). -/// Content of the file encoded in Base64. +/// +/// A stream containing the attachment's contents, encoded in Base64. [GenerateMethodsForProperties] public partial class Base64AttachmentProperties(string fileName, Stream stream) : AttachmentProperties(fileName, stream) { @@ -112,10 +107,10 @@ public override HttpContent Serialize() } /// -/// +/// Represents an attachment with quoted-printable encoded contents. /// -/// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). -/// Content of the file encoded in Quoted-Printable. +/// +/// A stream containing the attachment's contents, encoded in quoted-printable. [GenerateMethodsForProperties] public partial class QuotedPrintableAttachmentProperties(string fileName, Stream stream) : AttachmentProperties(fileName, stream) { @@ -128,17 +123,17 @@ public override HttpContent Serialize() } /// -/// +/// Represents an attachment hosted on Google Cloud. /// -/// Name of the file (max 1024 characters for attachments sent by message, 2-30 characters for attachments used for sticker creation). -/// Name of the upload. +/// +/// [GenerateMethodsForProperties] public partial class GoogleCloudPlatformAttachmentProperties(string fileName, string uploadedFileName) : AttachmentProperties(fileName) { private static readonly JsonEncodedText _uploadedFileName = JsonEncodedText.Encode("uploaded_filename"); /// - /// Name of the upload. + /// The filename to use for the upload. /// public string UploadedFileName { get; set; } = uploadedFileName; diff --git a/NetCord/Rest/EmbedAuthorProperties.cs b/NetCord/Rest/EmbedAuthorProperties.cs index a4d3c6987..df75e5a3a 100644 --- a/NetCord/Rest/EmbedAuthorProperties.cs +++ b/NetCord/Rest/EmbedAuthorProperties.cs @@ -2,26 +2,21 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class EmbedAuthorProperties { - /// - /// Name of the author. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("name")] public string? Name { get; set; } - /// - /// Url of the author. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("url")] public string? Url { get; set; } - /// - /// Url of the author icon. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("icon_url")] public string? IconUrl { get; set; } diff --git a/NetCord/Rest/EmbedFieldProperties.cs b/NetCord/Rest/EmbedFieldProperties.cs index 938bb4312..ade284d86 100644 --- a/NetCord/Rest/EmbedFieldProperties.cs +++ b/NetCord/Rest/EmbedFieldProperties.cs @@ -3,25 +3,22 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class EmbedFieldProperties { - /// - /// Name of the field. - /// + /// [JsonConverter(typeof(EmptyWhenNullStringConverter))] [JsonPropertyName("name")] public string? Name { get; set; } - /// - /// Value of the field. - /// + /// [JsonConverter(typeof(EmptyWhenNullStringConverter))] [JsonPropertyName("value")] public string? Value { get; set; } /// - /// Whether or not the field should display inline. + /// When set alongside another field with set, displays the fields side by side when supported. /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("inline")] diff --git a/NetCord/Rest/EmbedFooterProperties.cs b/NetCord/Rest/EmbedFooterProperties.cs index 7f453d438..4f7ba2e22 100644 --- a/NetCord/Rest/EmbedFooterProperties.cs +++ b/NetCord/Rest/EmbedFooterProperties.cs @@ -2,18 +2,18 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class EmbedFooterProperties { - /// - /// Text of the footer. - /// + + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("text")] public string? Text { get; set; } /// - /// Url of the footer icon. + /// Points to an image, which is displayed in a small circular format to the left of the . /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("icon_url")] diff --git a/NetCord/Rest/EmbedImageProperties.cs b/NetCord/Rest/EmbedImageProperties.cs index 852e238c3..46887252a 100644 --- a/NetCord/Rest/EmbedImageProperties.cs +++ b/NetCord/Rest/EmbedImageProperties.cs @@ -2,16 +2,12 @@ namespace NetCord.Rest; -/// -/// Url of the image. -/// -/// +/// +/// [GenerateMethodsForProperties] public partial class EmbedImageProperties(string? url) { - /// - /// Url of the image. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("url")] public string? Url { get; set; } = url; diff --git a/NetCord/Rest/EmbedProperties.cs b/NetCord/Rest/EmbedProperties.cs index c868b74fa..0be0d01aa 100644 --- a/NetCord/Rest/EmbedProperties.cs +++ b/NetCord/Rest/EmbedProperties.cs @@ -2,74 +2,65 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class EmbedProperties { /// - /// Title of the embed. + /// The text that is placed above the description, usually highlighted. Also directs to a URL if one is given in , has a 256 character limit. /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("title")] public string? Title { get; set; } - /// - /// Description of the embed. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("description")] public string? Description { get; set; } /// - /// Url of the embed. + /// A link to an address of a webpage. When set, the becomes a clickable link, directing to the URL. /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("url")] public string? Url { get; set; } /// - /// Timestamp of the embed. + /// Displays time in a format similar to a message timestamp. Located next to the . /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// - /// Color of the embed. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("color")] public Color Color { get; set; } - /// - /// Footer of the embed. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("footer")] public EmbedFooterProperties? Footer { get; set; } /// - /// Image of the embed. + /// The image included in the embed, displayed as a large-sized image located below the element. /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("image")] public EmbedImageProperties? Image { get; set; } - /// - /// Thumbnail of the embed. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("thumbnail")] public EmbedThumbnailProperties? Thumbnail { get; set; } - /// - /// Author of the embed. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("author")] public EmbedAuthorProperties? Author { get; set; } /// - /// Fields of the embed. + /// Allows the addition of multiple subtitles with additional content underneath them below the main and blocks, maximum of 25 per embed. /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("fields")] diff --git a/NetCord/Rest/EmbedThumbnailProperties.cs b/NetCord/Rest/EmbedThumbnailProperties.cs index ac324e17a..5d02e8222 100644 --- a/NetCord/Rest/EmbedThumbnailProperties.cs +++ b/NetCord/Rest/EmbedThumbnailProperties.cs @@ -2,16 +2,12 @@ namespace NetCord.Rest; -/// -/// -/// -/// Url of the thumbnail. +/// +/// [GenerateMethodsForProperties] public partial class EmbedThumbnailProperties(string? url) { - /// - /// Url of the thumbnail. - /// + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("url")] public string? Url { get; set; } = url; diff --git a/NetCord/Rest/ForumGuildThreadMessageProperties.cs b/NetCord/Rest/ForumGuildThreadMessageProperties.cs index 31549f720..f6fc16344 100644 --- a/NetCord/Rest/ForumGuildThreadMessageProperties.cs +++ b/NetCord/Rest/ForumGuildThreadMessageProperties.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a message sent in a . +/// [GenerateMethodsForProperties] public partial class ForumGuildThreadMessageProperties : IMessageProperties { @@ -21,6 +24,9 @@ public partial class ForumGuildThreadMessageProperties : IMessageProperties [JsonPropertyName("components")] public IEnumerable? Components { get; set; } + /// + /// A list of up to 3 sticker IDs to include in the message. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("sticker_ids")] public IEnumerable? StickerIds { get; set; } diff --git a/NetCord/Rest/GuildStickerOptions.cs b/NetCord/Rest/GuildStickerOptions.cs index b3189f6f8..86f728f6b 100644 --- a/NetCord/Rest/GuildStickerOptions.cs +++ b/NetCord/Rest/GuildStickerOptions.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a modification to perform on a . +/// [GenerateMethodsForProperties] public partial class GuildStickerOptions { @@ -9,14 +12,22 @@ internal GuildStickerOptions() { } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("name")] public string? Name { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("description")] public string? Description { get; set; } + /// + /// A comma separated-list of the sticker's autocomplete/suggestion tags. + /// + /// + /// The string's character count cannot exceed 200. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("tags")] public string? Tags { get; set; } diff --git a/NetCord/Rest/GuildStickerProperties.cs b/NetCord/Rest/GuildStickerProperties.cs index f330d8db5..05bf8b7f8 100644 --- a/NetCord/Rest/GuildStickerProperties.cs +++ b/NetCord/Rest/GuildStickerProperties.cs @@ -40,9 +40,9 @@ public HttpContent Serialize() var content = attachment.Serialize(); content.Headers.ContentType = new(Format switch { - StickerFormat.Png or StickerFormat.Apng => "image/png", + StickerFormat.PNG or StickerFormat.APNG => "image/png", StickerFormat.Lottie => "application/json", - StickerFormat.Gif => "image/gif", + StickerFormat.GIF => "image/gif", _ => throw new System.ComponentModel.InvalidEnumArgumentException(null, (int)Format, typeof(StickerFormat)), }); diff --git a/NetCord/Rest/GuildThreadUser.cs b/NetCord/Rest/GuildThreadUser.cs index cc2f7cdb9..224c5851b 100644 --- a/NetCord/Rest/GuildThreadUser.cs +++ b/NetCord/Rest/GuildThreadUser.cs @@ -2,7 +2,14 @@ namespace NetCord.Rest; +/// +/// Represents a with an included user object. +/// public partial class GuildThreadUser(JsonThreadUser jsonModel, RestClient client) : ThreadUser(jsonModel, client) { + /// + /// The thread user's object. + /// + public PartialGuildUser GuildUser { get; } = new(jsonModel.GuildUser!, client); } diff --git a/NetCord/Rest/IMessageProperties.cs b/NetCord/Rest/IMessageProperties.cs index 06963eca9..116595eda 100644 --- a/NetCord/Rest/IMessageProperties.cs +++ b/NetCord/Rest/IMessageProperties.cs @@ -5,16 +5,34 @@ namespace NetCord.Rest; [GenerateMethodsForProperties] public partial interface IMessageProperties { + /// + /// The text contents of a message, limited to 2000 characters. This limit is raised to 4000 characters for Discord Nitro subscribers. + /// public string? Content { get; set; } + /// + /// A list of up to 10 embeds to include, totalling up to 6000 characters. + /// public IEnumerable? Embeds { get; set; } + /// + /// Defines which users and roles the message is allowed to mention. + /// public AllowedMentionsProperties? AllowedMentions { get; set; } + /// + /// A list of attachments to include in the message. + /// public IEnumerable? Attachments { get; set; } + /// + /// A list of components to include in the message. + /// public IEnumerable? Components { get; set; } + /// + /// Includes additional information about the message's state. + /// public MessageFlags? Flags { get; set; } internal static HttpContent Serialize(TMessage message, JsonTypeInfo messageTypeInfo, IEnumerable? attachments) diff --git a/NetCord/Rest/IncomingWebhook.cs b/NetCord/Rest/IncomingWebhook.cs index b9b70432d..15703ccd9 100644 --- a/NetCord/Rest/IncomingWebhook.cs +++ b/NetCord/Rest/IncomingWebhook.cs @@ -2,10 +2,20 @@ namespace NetCord.Rest; +/// +/// Represents a newly-created webhook, containing its token and standard fields. +/// public partial class IncomingWebhook(JsonWebhook jsonModel, RestClient client) : Webhook(jsonModel, client) { + /// + /// The token of the newly created webhook. + /// public string Token => _jsonModel.Token!; + /// + /// Creates a usable from the webhook object directly. + /// + /// The configuration to pass to the client. public WebhookClient ToClient(WebhookClientConfiguration? configuration = null) { if (configuration is { Client: not null }) diff --git a/NetCord/Rest/MessageCall.cs b/NetCord/Rest/MessageCall.cs index da24bccf5..a1d1a3d23 100644 --- a/NetCord/Rest/MessageCall.cs +++ b/NetCord/Rest/MessageCall.cs @@ -2,11 +2,21 @@ namespace NetCord.Rest; +/// +/// Represents a call in a private channel. +/// +/// public class MessageCall(JsonMessageCall jsonModel) : IJsonModel { JsonMessageCall IJsonModel.JsonModel => jsonModel; + /// + /// A list of IDs, corresponding to the call's participating users. + /// public IReadOnlyList Participants => jsonModel.Participants; + /// + /// The timestamp of the call's end. + /// public DateTimeOffset? EndedAt => jsonModel.EndedAt; } diff --git a/NetCord/Rest/MessageOptions.cs b/NetCord/Rest/MessageOptions.cs index c3cdb5bba..74a5e94fb 100644 --- a/NetCord/Rest/MessageOptions.cs +++ b/NetCord/Rest/MessageOptions.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a modification to apply to a message. +/// [GenerateMethodsForProperties] public partial class MessageOptions : IHttpSerializable { @@ -9,26 +12,32 @@ internal MessageOptions() { } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("content")] public string? Content { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("embeds")] public IEnumerable? Embeds { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("flags")] public MessageFlags? Flags { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("allowed_mentions")] public AllowedMentionsProperties? AllowedMentions { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("components")] public IEnumerable? Components { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonConverter(typeof(JsonConverters.AttachmentPropertiesIEnumerableConverter))] [JsonPropertyName("attachments")] diff --git a/NetCord/Rest/RestClient.Application.cs b/NetCord/Rest/RestClient.Application.cs index a4a8a00d3..f82d2062d 100644 --- a/NetCord/Rest/RestClient.Application.cs +++ b/NetCord/Rest/RestClient.Application.cs @@ -2,10 +2,21 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Retrieves the application associated with the current user. + /// + /// Optional properties to customize the REST request, can be . + /// A token to monitor for cancellation requests. Defaults to . [GenerateAlias([typeof(CurrentApplication)], CastType = typeof(Application), Modifiers = ["override"])] public async Task GetCurrentApplicationAsync(RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => new(await (await SendRequestAsync(HttpMethod.Get, $"/applications/@me", null, null, properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonApplication).ConfigureAwait(false), this); + /// + /// Modifies the application associated with the current user. + /// + /// An action representing the modification to be made. + /// Optional properties to customize the REST request, can be . + /// A token to monitor for cancellation requests. Defaults to . [GenerateAlias([typeof(CurrentApplication)])] public async Task ModifyCurrentApplicationAsync(Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { diff --git a/NetCord/Rest/RestClient.ApplicationRoleConnectionMetadata.cs b/NetCord/Rest/RestClient.ApplicationRoleConnectionMetadata.cs index 04fa5e06e..efcdfdf08 100644 --- a/NetCord/Rest/RestClient.ApplicationRoleConnectionMetadata.cs +++ b/NetCord/Rest/RestClient.ApplicationRoleConnectionMetadata.cs @@ -2,10 +2,23 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Returns a list of objects for the given application. + /// + /// The ID of the application to request data for. + /// Optional properties to customize the REST request, can be . + /// A token to monitor for cancellation requests. Defaults to . [GenerateAlias([typeof(CurrentApplication)], nameof(CurrentApplication.Id), TypeNameOverride = nameof(Application))] public async Task> GetApplicationRoleConnectionMetadataRecordsAsync(ulong applicationId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/applications/{applicationId}/role-connections/metadata", null, null, properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.IEnumerableJsonApplicationRoleConnectionMetadata).ConfigureAwait(false)).Select(m => new ApplicationRoleConnectionMetadata(m)).ToArray(); + /// + /// Updates an application's list, replacing it with the given list instead. + /// + /// The ID of the application to modify data for. + /// The list to overwrite the target data with. + /// Optional properties to customize the REST request, can be . + /// A token to monitor for cancellation requests. Defaults to . [GenerateAlias([typeof(CurrentApplication)], nameof(CurrentApplication.Id), TypeNameOverride = nameof(Application))] public async Task> UpdateApplicationRoleConnectionMetadataRecordsAsync(ulong applicationId, IEnumerable applicationRoleConnectionMetadataProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { diff --git a/NetCord/Rest/RestClient.AuditLog.cs b/NetCord/Rest/RestClient.AuditLog.cs index 866ce54d0..fb046922c 100644 --- a/NetCord/Rest/RestClient.AuditLog.cs +++ b/NetCord/Rest/RestClient.AuditLog.cs @@ -4,6 +4,12 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Returns a collection of audit log entries for a guild, to be enumerated asynchronously. + /// + /// The ID of the guild to acquire entries for. + /// Optional properties to customize result pagination, can be . + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] public IAsyncEnumerable GetGuildAuditLogAsync(ulong guildId, GuildAuditLogPaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { diff --git a/NetCord/Rest/RestClient.AutoModeration.cs b/NetCord/Rest/RestClient.AutoModeration.cs index 7120d44e7..4180e4bee 100644 --- a/NetCord/Rest/RestClient.AutoModeration.cs +++ b/NetCord/Rest/RestClient.AutoModeration.cs @@ -4,15 +4,35 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Retrieves a read-only list of configured automod rules for a guild. + /// + /// The ID of the guild to retrieve auto-moderation rules for. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] public async Task> GetAutoModerationRulesAsync(ulong guildId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/guilds/{guildId}/auto-moderation/rules", null, new(guildId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonAutoModerationRuleArray).ConfigureAwait(false)).Select(r => new AutoModerationRule(r, this)).ToArray(); + /// + /// Retrieves information about a specific auto-mod's rule configuration, for a specified guild. + /// + /// The ID of the guild to retrieve auto-moderation rules for. + /// The ID of the rule to retrieve information on. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] [GenerateAlias([typeof(AutoModerationRule)], nameof(AutoModerationRule.GuildId), nameof(AutoModerationRule.Id))] public async Task GetAutoModerationRuleAsync(ulong guildId, ulong autoModerationRuleId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => new(await (await SendRequestAsync(HttpMethod.Get, $"/guilds/{guildId}/auto-moderation/rules/{autoModerationRuleId}", null, new(guildId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonAutoModerationRule).ConfigureAwait(false), this); + /// + /// Creates a new auto-moderation rule for a specified guild. + /// + /// The ID of the guild to create the rule for.. + /// The properties of the auto-moderation rule to be created, including triggers, actions, and conditions. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] public async Task CreateAutoModerationRuleAsync(ulong guildId, AutoModerationRuleProperties autoModerationRuleProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -20,6 +40,14 @@ public async Task CreateAutoModerationRuleAsync(ulong guildI return new(await (await SendRequestAsync(HttpMethod.Post, content, $"/guilds/{guildId}/auto-moderation/rules", null, new(guildId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonAutoModerationRule).ConfigureAwait(false), this); } + /// + /// Modifies a pre-existing auto-moderation rule for a specified guild. + /// + /// The ID of the guild to modify the rule for.. + /// The ID of the rule to modify. + /// An action, representing the modifications to make to the rule. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] [GenerateAlias([typeof(AutoModerationRule)], nameof(AutoModerationRule.GuildId), nameof(AutoModerationRule.Id))] public async Task ModifyAutoModerationRuleAsync(ulong guildId, ulong autoModerationRuleId, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -30,6 +58,13 @@ public async Task ModifyAutoModerationRuleAsync(ulong guildI return new(await (await SendRequestAsync(HttpMethod.Patch, content, $"/guilds/{guildId}/auto-moderation/rules/{autoModerationRuleId}", null, new(guildId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonAutoModerationRule).ConfigureAwait(false), this); } + /// + /// Deletes an auto-moderation rule for a specified guild. + /// + /// The ID of the guild to modify the rule for.. + /// The ID of the rule to modify. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] [GenerateAlias([typeof(AutoModerationRule)], nameof(AutoModerationRule.GuildId), nameof(AutoModerationRule.Id))] public Task DeleteAutoModerationRuleAsync(ulong guildId, ulong autoModerationRuleId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) diff --git a/NetCord/Rest/RestClient.Channel.cs b/NetCord/Rest/RestClient.Channel.cs index ed9f1acc4..55cae87cd 100644 --- a/NetCord/Rest/RestClient.Channel.cs +++ b/NetCord/Rest/RestClient.Channel.cs @@ -9,10 +9,23 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Retrieves a channel by its ID. + /// + /// The ID of the channel to retrieve. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(Channel)], nameof(Channel.Id), Cast = true)] public async Task GetChannelAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => Channel.CreateFromJson(await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonChannel).ConfigureAwait(false), this); + /// + /// Modifies a group DM channel’s properties. + /// + /// The ID of the group DM channel to modify. + /// An action delegate used to configure the channel’s updated properties. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GroupDMChannel)], nameof(GroupDMChannel.Id), Cast = true)] public async Task ModifyGroupDMChannelAsync(ulong channelId, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -22,6 +35,13 @@ public async Task ModifyGroupDMChannelAsync(ulong channelId, Action + /// Modifies a guild channel’s configuration. + /// + /// The ID of the guild channel to modify. + /// An action delegate used to configure the updated channel options. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IGuildChannel)], nameof(IGuildChannel.Id), Cast = true)] public async Task ModifyGuildChannelAsync(ulong channelId, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -31,6 +51,13 @@ public async Task ModifyGuildChannelAsync(ulong channelId, Action + /// Sets a guild voice channel's status. + /// + /// The ID of the guild voice channel to update. + /// The status to apply to the channel. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(VoiceGuildChannel)], nameof(VoiceGuildChannel.Id))] public async Task SetVoiceGuildChannelStatusAsync(ulong channelId, VoiceGuildChannelStatusProperties statusProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -38,10 +65,22 @@ public async Task SetVoiceGuildChannelStatusAsync(ulong channelId, VoiceGuildCha await SendRequestAsync(HttpMethod.Put, content, $"/channels/{channelId}/voice-status", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Deletes a channel. + /// + /// The ID of the channel to delete. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(Channel)], nameof(Channel.Id), Cast = true)] public async Task DeleteChannelAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => Channel.CreateFromJson(await (await SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonChannel).ConfigureAwait(false), this); + /// + /// Retrieves an , representing the messages of a specific channel. + /// + /// The ID of the channel to retrieve messages from. + /// Optional properties to customize result pagination, can be . + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public IAsyncEnumerable GetMessagesAsync(ulong channelId, PaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { @@ -64,10 +103,25 @@ public IAsyncEnumerable GetMessagesAsync(ulong channelId, Paginatio properties); } + /// + /// Retrieves a list of messages around a specific message ID within a channel. + /// + /// The ID of the channel to retrieve messages from. + /// The ID of the message to center the result around. + /// The maximum number of messages to retrieve, or to use the default. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public async Task> GetMessagesAroundAsync(ulong channelId, ulong messageId, int? limit = null, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}/messages", $"?limit={limit.GetValueOrDefault(100)}&around={messageId}", new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessageArray).ConfigureAwait(false)).Select(m => new RestMessage(m, this)).ToArray(); + /// + /// Performs a search within a guild according to a set of specified filters. + /// + /// The ID of the guild to search through. + /// Optional properties to customize result pagination and filtering, can be . + /// Optional properties to customize the request, can be . + /// [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] public IAsyncEnumerable SearchGuildMessagesAsync(ulong guildId, GuildMessagesSearchPaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { @@ -300,11 +354,26 @@ static string InvalidEnum(string propertyName) } } + /// + /// Retrieves a message from a channel by its ID. + /// + /// The ID of the channel containing the message. + /// The ID of the message to retrieve. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. + /// [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public async Task GetMessageAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => new(await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}/messages/{messageId}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); + /// + /// Sends a new message to the specified text channel. + /// + /// The ID of the channel to send the message to. + /// The content and properties of the message to send. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), TypeNameOverride = "Message")] public async Task SendMessageAsync(ulong channelId, MessageProperties message, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -313,27 +382,67 @@ public async Task SendMessageAsync(ulong channelId, MessageProperti return new(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/messages", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); } + /// + /// Crossposts a message from an announcement channel to subscribed channels. + /// + /// The ID of the announcement channel containing the message. + /// The ID of the message to crosspost. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(AnnouncementGuildChannel)], nameof(AnnouncementGuildChannel.Id))] [GenerateAlias([typeof(AnnouncementGuildThread)], nameof(AnnouncementGuildThread.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public async Task CrosspostMessageAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => new(await (await SendRequestAsync(HttpMethod.Post, $"/channels/{channelId}/messages/{messageId}/crosspost", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); + /// + /// Adds a reaction to a specific message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to react to. + /// The emoji to use as the reaction. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task AddMessageReactionAsync(ulong channelId, ulong messageId, ReactionEmojiProperties emoji, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Put, $"/channels/{channelId}/messages/{messageId}/reactions/{ReactionEmojiToString(emoji)}/@me", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Removes the current user's reaction from a specific message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to remove the reaction from. + /// The emoji to remove as a reaction. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task DeleteCurrentUserMessageReactionAsync(ulong channelId, ulong messageId, ReactionEmojiProperties emoji, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/messages/{messageId}/reactions/{ReactionEmojiToString(emoji)}/@me", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Removes a specific user's reaction from a message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to remove the reaction from. + /// The emoji to remove as a reaction. + /// The ID of the user whose reaction will be removed. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task DeleteUserMessageReactionAsync(ulong channelId, ulong messageId, ReactionEmojiProperties emoji, ulong userId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/messages/{messageId}/reactions/{ReactionEmojiToString(emoji)}/{userId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Retrieves a paginated list of users who reacted to a message with a specific emoji. + /// + /// The ID of the channel containing the message. + /// The ID of the message to retrieve reactions for. + /// The emoji to filter reactions by. + /// Pagination options for fetching users, or to use defaults. + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public IAsyncEnumerable GetMessageReactionsAsync(ulong channelId, ulong messageId, ReactionEmojiProperties emoji, MessageReactionsPaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) @@ -354,11 +463,26 @@ public IAsyncEnumerable GetMessageReactionsAsync(ulong channelId, ulong me properties); } + /// + /// Removes all reactions from a message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to clear reactions from. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task DeleteAllMessageReactionsAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/messages/{messageId}/reactions", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Removes all reactions of a specific emoji from a message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to clear emoji reactions from. + /// The emoji to remove from all users. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task DeleteAllMessageReactionsForEmojiAsync(ulong channelId, ulong messageId, ReactionEmojiProperties emoji, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -370,6 +494,14 @@ private static string ReactionEmojiToString(ReactionEmojiProperties emoji) return id.HasValue ? $"{emoji.Name}:{id.GetValueOrDefault()}" : Uri.EscapeDataString(emoji.Name); } + /// + /// Modifies the contents of a specific message. + /// + /// The ID of the channel containing the message. + /// The ID of the message to modify. + /// An action that sets the new message properties. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public async Task ModifyMessageAsync(ulong channelId, ulong messageId, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -380,11 +512,25 @@ public async Task ModifyMessageAsync(ulong channelId, ulong message return new(await (await SendRequestAsync(HttpMethod.Patch, content, $"/channels/{channelId}/messages/{messageId}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); } + /// + /// Deletes a message from a channel by its ID. + /// + /// The ID of the channel containing the message. + /// The ID of the message to delete. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task DeleteMessageAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/messages/{messageId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Deletes multiple messages in bulk or individually depending on batch size. + /// + /// The ID of the channel containing the messages. + /// The list of message IDs to delete. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public async Task DeleteMessagesAsync(ulong channelId, IEnumerable messageIds, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -422,6 +568,13 @@ private async Task BulkDeleteMessagesAsync(ulong channelId, ReadOnlyMemory + /// Modifies the permissions of a role or user in a guild channel. + /// + /// The ID of the guild channel to update permissions for. + /// The permission overwrite to apply. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IGuildChannel)], nameof(IGuildChannel.Id))] public async Task ModifyGuildChannelPermissionsAsync(ulong channelId, PermissionOverwriteProperties permissionOverwrite, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -429,10 +582,23 @@ public async Task ModifyGuildChannelPermissionsAsync(ulong channelId, Permission await SendRequestAsync(HttpMethod.Put, content, $"/channels/{channelId}/permissions/{permissionOverwrite.Id}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieves a list of active invites for a guild channel. + /// + /// The ID of the channel to retrieve invites for. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IGuildChannel)], nameof(IGuildChannel.Id))] public async Task> GetGuildChannelInvitesAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}/invites", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonRestInviteArray).ConfigureAwait(false)).Select(r => new RestInvite(r, this)); + /// + /// Creates a new invite for a guild channel. + /// + /// The ID of the guild channel to create the invite for. + /// The properties to configure the new invite. Can be for defaults. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IGuildChannel)], nameof(IGuildChannel.Id))] public async Task CreateGuildChannelInviteAsync(ulong channelId, InviteProperties? inviteProperties = null, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -443,10 +609,24 @@ public async Task CreateGuildChannelInviteAsync(ulong channelId, Inv return new(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/invites", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonRestInvite).ConfigureAwait(false), this); } + /// + /// Deletes a permission overwrite for a user or role in a guild channel. + /// + /// The ID of the guild channel. + /// The ID of the role or user whose permission overwrite is to be deleted. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IGuildChannel)], nameof(IGuildChannel.Id))] public Task DeleteGuildChannelPermissionAsync(ulong channelId, ulong overwriteId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/permissions/{overwriteId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Follows an announcement channel to another channel. + /// + /// The ID of the source announcement channel. + /// The ID of the channel to receive crossposted messages. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(AnnouncementGuildChannel)], nameof(AnnouncementGuildChannel.Id))] [GenerateAlias([typeof(AnnouncementGuildThread)], nameof(AnnouncementGuildThread.Id), TypeNameOverride = nameof(AnnouncementGuildChannel))] public async Task FollowAnnouncementGuildChannelAsync(ulong channelId, ulong webhookChannelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -455,10 +635,23 @@ public async Task FollowAnnouncementGuildChannelAsync(ulong cha return new(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/followers", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonFollowedChannel).ConfigureAwait(false), this); } + /// + /// Sends a typing indicator to the channel. + /// + /// The ID of the channel to trigger typing in. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public Task TriggerTypingAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Post, $"/channels/{channelId}/typing", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Enters a persistent typing state for the current user. + /// + /// The ID of the channel to type in. + /// Optional properties to customize the typing interval, can be . + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public ValueTask EnterTypingScopeAsync(ulong channelId, TypingScopeProperties? scopeProperties = null, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -467,26 +660,60 @@ public ValueTask EnterTypingScopeAsync(ulong channelId, TypingScope return new ValueTask(scope, scope.Version); } + /// + /// Enters a persistent typing state for the current user. + /// + /// The ID of the channel to type in. + /// Optional properties to customize the typing interval, can be . + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public IDisposable EnterTypingScope(ulong channelId, TypingScopeProperties? scopeProperties = null, RestRequestProperties? properties = null) { return new TypingScope(this, channelId, scopeProperties, properties); } + /// + /// Retrieves all pinned messages in a channel. + /// + /// The ID of the channel to get pinned messages from. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] public async Task> GetPinnedMessagesAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}/pins", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessageArray).ConfigureAwait(false)).Select(m => new RestMessage(m, this)).ToArray(); + /// + /// Pins a message in a channel. + /// + /// The ID of the channel containing the message. + /// The ID of the message to pin. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task PinMessageAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Put, $"/channels/{channelId}/pins/{messageId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Unpins a message from a channel. + /// + /// The ID of the channel containing the message. + /// The ID of the message to unpin. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextChannel)], nameof(TextChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public Task UnpinMessageAsync(ulong channelId, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/pins/{messageId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Adds a recipient to a group DM channel. + /// + /// The ID of the group DM channel. + /// The ID of the user to add. + /// Properties for adding the user, such as access tokens. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GroupDMChannel)], nameof(GroupDMChannel.Id))] public async Task GroupDMChannelAddUserAsync(ulong channelId, ulong userId, GroupDMChannelUserAddProperties groupDMChannelUserAddProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -494,10 +721,25 @@ public async Task GroupDMChannelAddUserAsync(ulong channelId, ulong userId, Grou await SendRequestAsync(HttpMethod.Put, content, $"/channels/{channelId}/recipients/{userId}", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Removes a recipient from a group DM channel. + /// + /// The ID of the group DM channel. + /// The ID of the user to remove. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GroupDMChannel)], nameof(GroupDMChannel.Id))] public Task GroupDMChannelDeleteUserAsync(ulong channelId, ulong userId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{channelId}/recipients/{userId}", null, new(channelId), properties, cancellationToken: cancellationToken); + /// + /// Creates a thread from an existing message in a text channel. + /// + /// The ID of the text channel containing the message. + /// The ID of the message to start the thread from. + /// The properties of the thread to create. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] [GenerateAlias([typeof(RestMessage)], nameof(RestMessage.ChannelId), nameof(RestMessage.Id), TypeNameOverride = "Message")] public async Task CreateGuildThreadAsync(ulong channelId, ulong messageId, GuildThreadFromMessageProperties threadFromMessageProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -506,6 +748,13 @@ public async Task CreateGuildThreadAsync(ulong channelId, ulong mes return GuildThread.CreateFromJson(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/messages/{messageId}/threads", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonChannel).ConfigureAwait(false), this); } + /// + /// Creates a standalone thread in a text channel. + /// + /// The ID of the text channel to create the thread in. + /// The properties of the thread to create. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public async Task CreateGuildThreadAsync(ulong channelId, GuildThreadProperties threadProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -513,6 +762,13 @@ public async Task CreateGuildThreadAsync(ulong channelId, GuildThre return GuildThread.CreateFromJson(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/threads", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonChannel).ConfigureAwait(false), this); } + /// + /// Creates a new thread in a forum channel. + /// + /// The ID of the forum channel. + /// The properties of the forum thread to create. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(ForumGuildChannel)], nameof(ForumGuildChannel.Id))] public async Task CreateForumGuildThreadAsync(ulong channelId, ForumGuildThreadProperties threadProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -520,23 +776,57 @@ public async Task CreateForumGuildThreadAsync(ulong channelId, return new ForumGuildThread(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/threads", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonChannel).ConfigureAwait(false), this); } + /// + /// Joins the current user to a thread. + /// + /// The ID of the thread to join. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] public Task JoinGuildThreadAsync(ulong threadId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Put, $"/channels/{threadId}/thread-members/@me", null, new(threadId), properties, cancellationToken: cancellationToken); + /// + /// Adds another user to a thread. + /// + /// The ID of the thread. + /// The ID of the user to add to the thread. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] public Task AddGuildThreadUserAsync(ulong threadId, ulong userId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Put, $"/channels/{threadId}/thread-members/{userId}", null, new(threadId), properties, cancellationToken: cancellationToken); + /// + /// Removes the current user from a thread. + /// + /// The ID of the thread to leave. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] public Task LeaveGuildThreadAsync(ulong threadId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{threadId}/thread-members/@me", null, new(threadId), properties, cancellationToken: cancellationToken); + /// + /// Removes a user from a thread. + /// + /// The ID of the thread. + /// The ID of the user to remove from the thread. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] [GenerateAlias([typeof(GuildThreadUser)], nameof(GuildThreadUser.ThreadId), nameof(GuildThreadUser.Id))] public Task DeleteGuildThreadUserAsync(ulong threadId, ulong userId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/channels/{threadId}/thread-members/{userId}", null, new(threadId), properties, cancellationToken: cancellationToken); + /// + /// Retrieves a thread member object for a user in the thread. + /// + /// The ID of the thread. + /// The ID of the user to fetch thread membership info for. + /// Whether to include full guild member info in the response. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] public async Task GetGuildThreadUserAsync(ulong threadId, ulong userId, bool withGuildUser = false, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -544,6 +834,12 @@ public async Task GetGuildThreadUserAsync(ulong threadId, ulong user return withGuildUser ? new GuildThreadUser(user, this) : new ThreadUser(user, this); } + /// + /// Retrieves a list of users participating in a thread. + /// + /// The ID of the thread. + /// Pagination options for fetching users, or to use defaults. + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(GuildThread)], nameof(GuildThread.Id))] public IAsyncEnumerable GetGuildThreadUsersAsync(ulong threadId, OptionalGuildUsersPaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { @@ -565,6 +861,12 @@ public IAsyncEnumerable GetGuildThreadUsersAsync(ulong threadId, Opt properties); } + /// + /// Retrieves public archived threads in the channel. + /// + /// The ID of the text channel. + /// Pagination options for archived threads, or to use defaults. + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public IAsyncEnumerable GetPublicArchivedGuildThreadsAsync(ulong channelId, PaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { @@ -586,6 +888,12 @@ public IAsyncEnumerable GetPublicArchivedGuildThreadsAsync(ulong ch properties); } + /// + /// Retrieves private archived threads in the channel. + /// + /// The ID of the text channel. + /// Pagination options for archived threads, or to use defaults. + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public IAsyncEnumerable GetPrivateArchivedGuildThreadsAsync(ulong channelId, PaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { @@ -607,6 +915,12 @@ public IAsyncEnumerable GetPrivateArchivedGuildThreadsAsync(ulong c properties); } + /// + /// Retrieves private archived threads joined by the current user. + /// + /// The ID of the text channel. + /// Pagination options for archived threads, or to use defaults. + /// Optional properties to customize the request, can be . [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public IAsyncEnumerable GetJoinedPrivateArchivedGuildThreadsAsync(ulong channelId, PaginationProperties? paginationProperties = null, RestRequestProperties? properties = null) { diff --git a/NetCord/Rest/RestClient.Webhook.cs b/NetCord/Rest/RestClient.Webhook.cs index 5c6d5afc3..c803ee552 100644 --- a/NetCord/Rest/RestClient.Webhook.cs +++ b/NetCord/Rest/RestClient.Webhook.cs @@ -4,6 +4,16 @@ namespace NetCord.Rest; public partial class RestClient { + /// + /// Creates a new webhook, and returns an object on success. + /// + /// + /// Requires the permission, and fires a event. + /// + /// The ID of the channel to create the webhook in. + /// Properties to customize the webhook's appearance. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(ForumGuildChannel)], nameof(ForumGuildChannel.Id))] [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public async Task CreateWebhookAsync(ulong channelId, WebhookProperties webhookProperties, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -12,24 +22,68 @@ public async Task CreateWebhookAsync(ulong channelId, WebhookPr return new(await (await SendRequestAsync(HttpMethod.Post, content, $"/channels/{channelId}/webhooks", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhook).ConfigureAwait(false), this); } + /// + /// Returns a list of channel objects. + /// + /// The ID of the channel to retrieve webhooks for. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(ForumGuildChannel)], nameof(ForumGuildChannel.Id))] [GenerateAlias([typeof(TextGuildChannel)], nameof(TextGuildChannel.Id))] public async Task> GetChannelWebhooksAsync(ulong channelId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/channels/{channelId}/webhooks", null, new(channelId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhookArray).ConfigureAwait(false)).Select(w => Webhook.CreateFromJson(w, this)).ToArray(); + /// + /// Retrieves a list of webhooks for the specified guild ID. + /// + /// + /// Requires the permission. + /// + /// The ID of the guild to retrieve webhooks for. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(RestGuild)], nameof(RestGuild.Id), TypeNameOverride = nameof(Guild))] public async Task> GetGuildWebhooksAsync(ulong guildId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => (await (await SendRequestAsync(HttpMethod.Get, $"/guilds/{guildId}/webhooks", null, new(guildId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhookArray).ConfigureAwait(false)).Select(w => Webhook.CreateFromJson(w, this)).ToArray(); + /// + /// Retrieves the new object for the given ID. + /// + /// + /// Requires the permission unless the application making the request owns the webhook. + /// + /// The ID of the webhook to retrieve. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(Webhook)], nameof(Webhook.Id), Cast = true)] public async Task GetWebhookAsync(ulong webhookId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => Webhook.CreateFromJson(await (await SendRequestAsync(HttpMethod.Get, $"/webhooks/{webhookId}", null, new(webhookId), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhook).ConfigureAwait(false), this); + /// + /// Retrieves the new object for the given ID. + /// + /// + /// Requires the permission unless the application making the request owns the webhook. + /// + /// The ID of the webhook to retrieve. + /// The token to use for authorization. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), Cast = true, TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = $"{nameof(Webhook)}WithToken")] public async Task GetWebhookWithTokenAsync(ulong webhookId, string webhookToken, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => Webhook.CreateFromJson(await (await SendRequestAsync(HttpMethod.Get, $"/webhooks/{webhookId}/{webhookToken}", null, new(webhookId, webhookToken), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhook).ConfigureAwait(false), this); + /// + /// Modifies a webhook, returning the updated object on success. + /// + /// + /// Requires the permission, and fires a event. + /// + /// The ID of the webhook to modify. + /// The modification to perform on the webhook. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(Webhook)], nameof(Webhook.Id), Cast = true)] public async Task ModifyWebhookAsync(ulong webhookId, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) { @@ -39,6 +93,18 @@ public async Task ModifyWebhookAsync(ulong webhookId, Action + /// Modifies a webhook, returning the updated object on success. + /// + /// + /// Requires the permission, and fires a event. + /// Does not allow modifiying the property. + /// + /// The ID of the webhook to modify. + /// The token to use for authorization. + /// The modification to perform on the webhook. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), Cast = true, TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = $"{nameof(Webhook)}WithToken")] public async Task ModifyWebhookWithTokenAsync(ulong webhookId, string webhookToken, Action action, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -49,15 +115,48 @@ public async Task ModifyWebhookWithTokenAsync(ulong webhookId, string w return Webhook.CreateFromJson(await (await SendRequestAsync(HttpMethod.Patch, content, $"/webhooks/{webhookId}/{webhookToken}", null, new(webhookId, webhookToken), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonWebhook).ConfigureAwait(false), this); } + /// + /// Deletes a webhook permanently. + /// + /// + /// Requires the permission, and fires a event. + /// + /// The ID of the webhook to delete. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(Webhook)], nameof(Webhook.Id))] public Task DeleteWebhookAsync(ulong webhookId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/webhooks/{webhookId}", null, new(webhookId), properties, cancellationToken: cancellationToken); + /// + /// Deletes a webhook permanently. + /// + /// + /// Requires the permission, and fires a event. + /// + /// The ID of the webhook to delete. + /// The token to use for authorization. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = $"{nameof(Webhook)}WithToken")] public Task DeleteWebhookWithTokenAsync(ulong webhookId, string webhookToken, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendRequestAsync(HttpMethod.Delete, $"/webhooks/{webhookId}/{webhookToken}", null, new(webhookId, webhookToken), properties, cancellationToken: cancellationToken); + /// + /// Executes a webhook with the given parameters, optionally returning the message result. + /// + /// The ID of the webhook to execute. + /// The token to use for authorization. + /// The message to send through the webhook. + /// If set, the returned will contain the sent message. + /// Optional ID of the thread to send the message in, within the webhook's target channel. Can be . + /// + /// Whether to respect the 's . + /// When enabled, allows application-owned webhooks to use all components, and non-owned webhooks to use non-interactive components. + /// + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = nameof(Webhook))] public async Task ExecuteWebhookAsync(ulong webhookId, string webhookToken, WebhookMessageProperties message, bool wait = false, ulong? threadId = null, bool withComponents = true, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -98,11 +197,34 @@ await SendRequestAsync(HttpMethod.Post, } } + /// + /// Returns a previously-sent webhook message from the given token. + /// + /// The ID of the webhook to retrieve the message from. + /// The token to use for authorization. + /// The ID of the message to retrieve. + /// The ID of the thread the message is in. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = nameof(Webhook))] - public async Task GetWebhookMessageAsync(ulong webhookId, string webhookToken, ulong messageId, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) - => new(await (await SendRequestAsync(HttpMethod.Get, $"/webhooks/{webhookId}/{webhookToken}/messages/{messageId}", null, new(webhookId, webhookToken), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); + public async Task GetWebhookMessageAsync(ulong webhookId, string webhookToken, ulong messageId, ulong? threadId = null, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) + => new(await (await SendRequestAsync(HttpMethod.Get, $"/webhooks/{webhookId}/{webhookToken}/messages/{messageId}", threadId.HasValue ? $"?thread_id={threadId.GetValueOrDefault()}" : null, new(webhookId, webhookToken), properties, cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); + /// + /// Modifies a previously-sent webhook message from the given token. + /// + /// The ID of the webhook to modify the message with. + /// The token to use for authorization. + /// The ID of the message to modify. + /// The modification to apply to the message. + /// The ID of the thread the message is in. + /// + /// Whether to respect the modification's . + /// When enabled, allows application-owned webhooks to use all components, and non-owned webhooks to use non-interactive components. + /// + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = nameof(Webhook))] public async Task ModifyWebhookMessageAsync(ulong webhookId, string webhookToken, ulong messageId, Action action, ulong? threadId = null, bool withComponents = true, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) @@ -125,6 +247,15 @@ public async Task ModifyWebhookMessageAsync(ulong webhookId, string cancellationToken: cancellationToken).ConfigureAwait(false)).ToObjectAsync(Serialization.Default.JsonMessage).ConfigureAwait(false), this); } + /// + /// Deletes a previously-sent webhook message permanently. + /// + /// The ID of the webhook to delete the message with. + /// The token to use for authorization. + /// The ID of the message to delete. + /// The ID of the thread the message is in. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. [GenerateAlias([typeof(IncomingWebhook)], nameof(IncomingWebhook.Id), nameof(IncomingWebhook.Token), TypeNameOverride = nameof(Webhook))] [GenerateAlias([typeof(WebhookClient)], nameof(WebhookClient.Id), nameof(WebhookClient.Token), TypeNameOverride = nameof(Webhook))] public Task DeleteWebhookMessageAsync(ulong webhookId, string webhookToken, ulong messageId, ulong? threadId = null, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) diff --git a/NetCord/Rest/RestGuild.cs b/NetCord/Rest/RestGuild.cs index 985e2bcbc..73a308b64 100644 --- a/NetCord/Rest/RestGuild.cs +++ b/NetCord/Rest/RestGuild.cs @@ -98,7 +98,7 @@ public int Compare(PartialGuildUser? x, PartialGuildUser? y) /// /// Gets the of the 's icon. /// - /// The format of the returned . Defaults to (or for animated icons). + /// The format of the returned . Defaults to (or for animated icons). /// An pointing to the guild's icon. If the guild does not have one set, returns . public ImageUrl? GetIconUrl(ImageFormat? format = null) => IconHash is string hash ? ImageUrl.GuildIcon(Id, hash, format) : null; @@ -262,7 +262,7 @@ public int Compare(PartialGuildUser? x, PartialGuildUser? y) /// /// Gets the of the 's banner. /// - /// The format of the returned . Defaults to (or for animated icons). + /// The format of the returned . Defaults to (or for animated icons). /// An pointing to the guild's banner. If the guild does not have one set, returns . public ImageUrl? GetBannerUrl(ImageFormat? format = null) => BannerHash is string hash ? ImageUrl.GuildBanner(Id, hash, format) : null; diff --git a/NetCord/Rest/RestMessage.cs b/NetCord/Rest/RestMessage.cs index 37f42d8fc..d69bb5bc2 100644 --- a/NetCord/Rest/RestMessage.cs +++ b/NetCord/Rest/RestMessage.cs @@ -32,7 +32,7 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) }).ToArray(); MentionedChannels = jsonModel.MentionedChannels.SelectOrEmpty(c => new GuildChannelMention(c)).ToArray(); - Attachments = jsonModel.Attachments!.Select(Attachment.CreateFromJson).ToArray(); + Attachments = jsonModel.Attachments!.Select(a => Attachment.CreateFromJson(a, client)).ToArray(); Embeds = jsonModel.Embeds!.Select(e => new Embed(e)).ToArray(); Reactions = jsonModel.Reactions.SelectOrEmpty(r => new MessageReaction(r)).ToArray(); @@ -73,7 +73,9 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) StartedThread = GuildThread.CreateFromJson(startedThread, client); Components = jsonModel.Components.SelectOrEmpty(IMessageComponent.CreateFromJson).ToArray(); +#pragma warning disable CS0618 // Type or member is obsolete Stickers = jsonModel.Stickers.SelectOrEmpty(s => new MessageSticker(s, client)).ToArray(); +#pragma warning restore CS0618 // Type or member is obsolete var roleSubscriptionData = jsonModel.RoleSubscriptionData; if (roleSubscriptionData is not null) @@ -90,6 +92,10 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) var call = jsonModel.Call; if (call is not null) Call = new(call); + + var theme = jsonModel.SharedClientTheme; + if (theme is not null) + SharedClientTheme = new(theme); } /// @@ -106,7 +112,7 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) /// The object of the message's author. /// /// - /// The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a , the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the on the message object. + /// If the message is generated by a , the object will correspond to the webhook's ID, username, and avatar. /// public User Author { get; } @@ -116,7 +122,7 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public string Content => _jsonModel.Content!; /// - /// When the message was edited (or null if never). + /// If the message has been edited, contains the timestamp of the latest edit, otherwise . /// public DateTimeOffset? EditedAt => _jsonModel.EditedAt; @@ -126,12 +132,12 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public bool IsTts => _jsonModel.IsTts.GetValueOrDefault(); /// - /// Whether the message mentions @everyone. + /// Whether the message mentions . /// public bool MentionEveryone => _jsonModel.MentionEveryone.GetValueOrDefault(); /// - /// A list of objects indexed by their IDs, containing users specifically mentioned in the message. + /// A list of users specifically mentioned in the message. /// public IReadOnlyList MentionedUsers { get; } @@ -144,22 +150,23 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) /// A list of objects indexed by their IDs, containing channels specifically mentioned in the message. /// /// - /// Not all channel mentions in a message will appear in . Only s visible to everyone in a lurkable guild will ever be included. Only crossposted messages (via Channel Following) currently include at all. If no s in the message meet these requirements, this field will not be sent. + /// This list is only populated for messages with the flag set. + /// Only text channels visible to everyone in a lurkable guild will ever be included. /// public IReadOnlyList MentionedChannels { get; } /// - /// A list of objects indexed by their IDs, containing any files attached in the message. + /// A list containing the message's attachments. /// public IReadOnlyList Attachments { get; } /// - /// A list of objects containing any embedded content present in the message. + /// A list of objects, representing any embedded content present in the message. /// public IReadOnlyList Embeds { get; } /// - /// A list of objects containing all reactions to the message. + /// A list of objects, representing all reactions to the message. /// public IReadOnlyList Reactions { get; } @@ -174,7 +181,7 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public bool IsPinned => _jsonModel.IsPinned.GetValueOrDefault(); /// - /// If the message was generated by a , this is the webhook's ID. + /// If the message was generated by a , contains the webhook's ID, otherwise . /// public ulong? WebhookId => _jsonModel.WebhookId; @@ -194,7 +201,7 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public Application? Application { get; } /// - /// If the message is an response/followup or an application-owned , the ID of the . + /// If the message is an response/followup or an application-owned , the ID of the . /// public ulong? ApplicationId => _jsonModel.ApplicationId; @@ -222,18 +229,18 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public RestMessage? ReferencedMessage { get; } /// - /// Sent if the message is sent as a result of an . + /// Sent if the message is sent as a result of an interaction. /// public MessageInteractionMetadata? InteractionMetadata { get; } /// - /// Sent if the message is a response to an . + /// Sent if the message is a response to an interaction. /// [Obsolete($"Replaced by '{nameof(InteractionMetadata)}'")] public MessageInteraction? Interaction { get; } /// - /// The that was started from this message. + /// The that was started from this message, if any. /// public GuildThread? StartedThread { get; } @@ -243,30 +250,53 @@ public RestMessage(NetCord.JsonModels.JsonMessage jsonModel, RestClient client) public IReadOnlyList Components { get; } /// - /// Contains stickers contained in the message, if any. + /// A list of stickers sent within the message. /// + [Obsolete("Deprecated by Discord.")] public IReadOnlyList Stickers { get; } /// /// A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a . - /// It can be used to estimate the relative position of the message in a thread in tandem with the property of the parent thread. /// + /// + /// It can be used to estimate the relative position of the message in a thread in tandem with the property of the parent thread. + /// public int? Position => _jsonModel.Position; /// - /// Data of the role subscription purchase or renewal that prompted this message. + /// Contains information about the role subscription purchase or renewal that prompted this message. /// public RoleSubscriptionData? RoleSubscriptionData { get; } /// - /// Data for s, s, s, and s in the message's auto-populated select s. + /// Contains information about the , , , and objects in the message's auto-populated selection menus. /// public InteractionResolvedData? ResolvedData { get; } + /// + /// The message's contained poll, if it has one, otherwise . + /// + /// + /// This is always if the intent is not set. + /// public MessagePoll? Poll { get; } + /// + /// The call associated with the message, if any. + /// public MessageCall? Call { get; } + /// + /// The custom client-side theme shared in the message, if any. + /// + public SharedClientTheme? SharedClientTheme { get; } + + /// + /// Replies to the message, returning the resulting reply. + /// + /// The message to reply with. + /// Optional properties to customize the request, can be . + /// A token that can be used to cancel the operation before it completes. public Task ReplyAsync(ReplyMessageProperties replyMessage, RestRequestProperties? properties = null, CancellationToken cancellationToken = default) => SendAsync(replyMessage.ToMessageProperties(Id), properties, cancellationToken); } diff --git a/NetCord/Rest/RestRequestProperties.cs b/NetCord/Rest/RestRequestProperties.cs index 3757b0ba3..0dd671bf5 100644 --- a/NetCord/Rest/RestRequestProperties.cs +++ b/NetCord/Rest/RestRequestProperties.cs @@ -1,5 +1,8 @@ namespace NetCord.Rest; +/// +/// A set of optional properties that can be used to customize most requests. +/// [GenerateMethodsForProperties] public sealed partial class RestRequestProperties { diff --git a/NetCord/Rest/StickerPack.cs b/NetCord/Rest/StickerPack.cs index 46dc96687..b83f3cd26 100644 --- a/NetCord/Rest/StickerPack.cs +++ b/NetCord/Rest/StickerPack.cs @@ -1,13 +1,39 @@ namespace NetCord.Rest; +/// +/// Represents a pack of standard stickers. +/// public class StickerPack(JsonModels.JsonStickerPack jsonModel) : IJsonModel { JsonModels.JsonStickerPack IJsonModel.JsonModel => jsonModel; + /// + /// A list of the stickers available within the pack. + /// public IReadOnlyList Stickers { get; } = jsonModel.Stickers.Select(s => new StandardSticker(s)).ToArray(); + + /// + /// The sticker pack's name. + /// public string Name => jsonModel.Name; + + /// + /// The sticker pack's SKU ID. + /// public ulong SkuId => jsonModel.SkuId; + + /// + /// An optional ID, corresponding to the sticker displayed as the pack icon. + /// public ulong? CoverStickerId => jsonModel.CoverStickerId; + + /// + /// The sticker pack's description. + /// public string Description => jsonModel.Description; + + /// + /// The ID corresponding to the sticker pack's banner image. + /// public ulong? BannerAssetId => jsonModel.BannerAssetId; } diff --git a/NetCord/Rest/Webhook.cs b/NetCord/Rest/Webhook.cs index e3d671223..8401dd79f 100644 --- a/NetCord/Rest/Webhook.cs +++ b/NetCord/Rest/Webhook.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a webhook, a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use. +/// public partial class Webhook : ClientEntity, IJsonModel { JsonWebhook IJsonModel.JsonModel => _jsonModel; @@ -24,26 +27,84 @@ public Webhook(JsonWebhook jsonModel, RestClient client) : base(client) Channel = Channel.CreateFromJson(channel, client); } + /// + /// The ID of the webhook. + /// public override ulong Id => _jsonModel.Id; + /// + /// The type of the webhook. + /// public WebhookType Type => _jsonModel.Type; + /// + /// The guild ID this webhook targets. Can be . + /// public ulong? GuildId => _jsonModel.GuildId; + /// + /// The channel ID this webhook targets. Can be . + /// public ulong? ChannelId => _jsonModel.ChannelId; + /// + /// The this webhook was created by. + /// + /// + /// This property is if the parent object was retrieved using its token. + /// public User? Creator { get; } + /// + /// The name of the webhook. + /// + /// + /// A webhook name is valid if: + /// + /// + /// The string length is between 1 and 80 characters. + /// + /// + /// It does not contain the substrings clyde or discord. + /// + /// + /// It follows Discord's nickname guidelines, found here. + /// + /// + /// public string? Name => _jsonModel.Name; + /// + /// The default user avatar hash of the webhook. + /// public string? AvatarHash => _jsonModel.AvatarHash; + /// + /// The ID of the bot or OAuth2 application that created this webhook. + /// public ulong? ApplicationId => _jsonModel.ApplicationId; + /// + /// The guild of the channel followed by this webhook. + /// + /// + /// This property is if is not , + /// or if the has lost access to the guild where the resides. + /// public RestGuild? Guild { get; } + /// + /// The channel that this webhook is following. + /// + /// + /// This property is if is not , + /// or if the has lost access to the guild where the resides. + /// public Channel? Channel { get; } + /// + /// The URL used for executing the webhook. + /// public string? Url => _jsonModel.Url; public static Webhook CreateFromJson(JsonWebhook jsonModel, RestClient client) => jsonModel.Type switch diff --git a/NetCord/Rest/WebhookClient.cs b/NetCord/Rest/WebhookClient.cs index 1fcda47f3..e8af63003 100644 --- a/NetCord/Rest/WebhookClient.cs +++ b/NetCord/Rest/WebhookClient.cs @@ -1,14 +1,29 @@ namespace NetCord.Rest; +/// +/// A specialized client that can be used to interact with webhook endpoints. +/// public sealed partial class WebhookClient : IDisposable { + /// + /// The ID of the webhook to use. + /// public ulong Id { get; } + /// + /// The token to use for authorization. + /// public string Token { get; } private readonly RestClient _client; private readonly bool _dispose; + /// + /// Creates a from its ID, token, and optional configuration. + /// + /// + /// + /// The configuration to pass to the client. public WebhookClient(ulong webhookId, string webhookToken, WebhookClientConfiguration? configuration = null) { Id = webhookId; diff --git a/NetCord/Rest/WebhookClientConfiguration.cs b/NetCord/Rest/WebhookClientConfiguration.cs index f6551c2e6..55514939d 100644 --- a/NetCord/Rest/WebhookClientConfiguration.cs +++ b/NetCord/Rest/WebhookClientConfiguration.cs @@ -1,6 +1,12 @@ namespace NetCord.Rest; +/// +/// Contains configuration info for a . +/// public class WebhookClientConfiguration { + /// + /// The client to use as a base for the webhook client. + /// public RestClient? Client { get; set; } } diff --git a/NetCord/Rest/WebhookMessageProperties.cs b/NetCord/Rest/WebhookMessageProperties.cs index 743547d06..3e6d3c9fc 100644 --- a/NetCord/Rest/WebhookMessageProperties.cs +++ b/NetCord/Rest/WebhookMessageProperties.cs @@ -1,22 +1,40 @@ using System.Text.Json.Serialization; +using NetCord.Gateway; + namespace NetCord.Rest; +/// +/// A specialized message object, for use with . +/// [GenerateMethodsForProperties] public partial class WebhookMessageProperties : IHttpSerializable, IMessageProperties { + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("content")] public string? Content { get; set; } + /// + /// Overrides the default username of the webhook. + /// + /// + /// Must follow the rules set for . + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("username")] public string? Username { get; set; } + /// + /// Overrides the default avatar of the webhook. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("avatar_url")] public string? AvatarUrl { get; set; } + /// + /// Whether the message is a Text-To-Speech message. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonPropertyName("tts")] public bool Tts { get; set; } diff --git a/NetCord/Rest/WebhookOptions.cs b/NetCord/Rest/WebhookOptions.cs index 481ab79cf..15353f19d 100644 --- a/NetCord/Rest/WebhookOptions.cs +++ b/NetCord/Rest/WebhookOptions.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a modification to perform on a object. +/// [GenerateMethodsForProperties] public partial class WebhookOptions { @@ -9,14 +12,19 @@ internal WebhookOptions() { } + /// c [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("name")] public string? Name { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("avatar")] public ImageProperties? Avatar { get; set; } + /// + /// The new channel ID to move the webhook to. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("channel_id")] public ulong? ChannelId { get; set; } diff --git a/NetCord/Rest/WebhookProperties.cs b/NetCord/Rest/WebhookProperties.cs index ed9f29cd9..6b9eab68b 100644 --- a/NetCord/Rest/WebhookProperties.cs +++ b/NetCord/Rest/WebhookProperties.cs @@ -2,12 +2,20 @@ namespace NetCord.Rest; +/// +/// Represents a webhook's name and avatar. +/// +/// [GenerateMethodsForProperties] public partial class WebhookProperties(string name) { + /// [JsonPropertyName("name")] public string Name { get; set; } = name; + /// + /// The for the default webhook avatar. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("avatar")] public ImageProperties? Avatar { get; set; } diff --git a/NetCord/Rest/WebhookType.cs b/NetCord/Rest/WebhookType.cs index c4fdd9c97..7023c1b02 100644 --- a/NetCord/Rest/WebhookType.cs +++ b/NetCord/Rest/WebhookType.cs @@ -1,8 +1,22 @@ namespace NetCord.Rest; +/// +/// Represents the type of a . +/// public enum WebhookType { + /// + /// Incoming webhooks can post messages to channels with a generated token. + /// Incoming = 1, + + /// + /// Channel Follower Webhooks are internal webhooks used with Channel Following to post new messages into channels. + /// ChannelFollower = 2, + + /// + /// Application webhooks are webhooks used via the system. + /// Application = 3, } diff --git a/NetCord/RoleSubscriptionData.cs b/NetCord/RoleSubscriptionData.cs index 186de7a05..9efc2e1a2 100644 --- a/NetCord/RoleSubscriptionData.cs +++ b/NetCord/RoleSubscriptionData.cs @@ -1,11 +1,14 @@ namespace NetCord; +/// +/// Contains information about a role subscribed to by a user. +/// public class RoleSubscriptionData(JsonModels.JsonRoleSubscriptionData jsonModel) : IJsonModel { JsonModels.JsonRoleSubscriptionData IJsonModel.JsonModel => jsonModel; /// - /// The ID of the sku and listing that the user is subscribed to. + /// The ID of the SKU and listing that the user is subscribed to. /// public ulong RoleSubscriptionListingId => jsonModel.RoleSubscriptionListingId; diff --git a/NetCord/SharedClientTheme.cs b/NetCord/SharedClientTheme.cs new file mode 100644 index 000000000..a38fa1c1d --- /dev/null +++ b/NetCord/SharedClientTheme.cs @@ -0,0 +1,31 @@ +using NetCord.JsonModels; + +namespace NetCord; + +/// +/// Represents a shared custom client theme. +/// +public class SharedClientTheme(JsonSharedClientTheme jsonModel) : IJsonModel +{ + public JsonSharedClientTheme JsonModel => jsonModel; + + /// + /// A list of the colors within the theme's gradient (maximum of 5). + /// + public IReadOnlyList Colors => jsonModel.Colors; + + /// + /// The direction of the theme's gradient (maximum of 360). + /// + public int GradientAngle => jsonModel.GradientAngle; + + /// + /// The intensity of the theme's gradient colors (maximum of 100). + /// + public int BaseMix => jsonModel.BaseMix; + + /// + /// The theme the client theme is based on. + /// + public BaseTheme BaseTheme => jsonModel.BaseTheme.GetValueOrDefault(); +} diff --git a/NetCord/SortOrderType.cs b/NetCord/SortOrderType.cs index c186785f7..8d650ae59 100644 --- a/NetCord/SortOrderType.cs +++ b/NetCord/SortOrderType.cs @@ -1,7 +1,17 @@ namespace NetCord; +/// +/// Determines the sort order for posts within a . +/// public enum SortOrderType { + /// + /// Sort forum posts by recent activity. + /// LatestActivity = 0, + + /// + /// Sort forum posts by their creation date, from newest to oldest. + /// CreationDate = 1, } diff --git a/NetCord/StandardSticker.cs b/NetCord/StandardSticker.cs index bf71eddf5..03e1ec09a 100644 --- a/NetCord/StandardSticker.cs +++ b/NetCord/StandardSticker.cs @@ -1,7 +1,19 @@ +using NetCord.Rest; + namespace NetCord; +/// +/// Represents an official Discord sticker. +/// public class StandardSticker(JsonModels.JsonSticker jsonModel) : Sticker(jsonModel) { + /// + /// The ID of the sticker's parent . + /// public ulong PackId => _jsonModel.PackId.GetValueOrDefault(); + + /// + /// The sticker's sort value within its parent . + /// public int? SortValue => _jsonModel.SortValue; } diff --git a/NetCord/Sticker.cs b/NetCord/Sticker.cs index ca4c81964..bfae74de9 100644 --- a/NetCord/Sticker.cs +++ b/NetCord/Sticker.cs @@ -1,18 +1,39 @@ namespace NetCord; +/// +/// Represents a sticker within Discord. +/// public abstract class Sticker : Entity, IJsonModel { JsonModels.JsonSticker IJsonModel.JsonModel => _jsonModel; private protected readonly JsonModels.JsonSticker _jsonModel; + /// + /// The sticker's unique ID. + /// public override ulong Id => _jsonModel.Id; + /// + /// The sticker's name. + /// public string Name => _jsonModel.Name; + /// + /// The sticker's description. + /// public string Description => _jsonModel.Description; + /// + /// A list of sticker tags, used for autocomplete/suggestions. + /// + /// + /// The total character count for all entries cannot exceed 200. + /// public IReadOnlyList Tags { get; } + /// + /// The sticker's image format. + /// public StickerFormat Format => _jsonModel.Format; private protected Sticker(JsonModels.JsonSticker jsonModel) diff --git a/NetCord/StickerFormat.cs b/NetCord/StickerFormat.cs index 3150a37eb..110525d99 100644 --- a/NetCord/StickerFormat.cs +++ b/NetCord/StickerFormat.cs @@ -1,9 +1,27 @@ namespace NetCord; +/// +/// Specifies a sticker's image format. +/// public enum StickerFormat { - Png = 1, - Apng = 2, + /// + /// An image in the PNG format. + /// + PNG = 1, + + /// + /// An animated image in the APNG format. + /// + APNG = 2, + + /// + /// An animated image in the Lottie format. Rarely available. + /// Lottie = 3, - Gif = 4, + + /// + /// An animated image in the GIF format. + /// + GIF = 4, } diff --git a/NetCord/ThreadArchiveDuration.cs b/NetCord/ThreadArchiveDuration.cs index 382a29538..61ed20156 100644 --- a/NetCord/ThreadArchiveDuration.cs +++ b/NetCord/ThreadArchiveDuration.cs @@ -1,9 +1,27 @@ namespace NetCord; +/// +/// Indicates how long a thread must be inactive before auto-archiving occurs. +/// public enum ThreadArchiveDuration { + /// + /// Auto-archiving will occur after an hour of inactivity. + /// OneHour = 60, + + /// + /// Auto-archiving will occur after one day of inactivity. + /// OneDay = 24 * OneHour, + + /// + /// Auto-archiving will occur after three days of inactivity. + /// ThreeDays = 3 * OneDay, + + /// + /// Auto-archiving will occur after one week of inactivity. + /// OneWeek = 7 * OneDay, } diff --git a/NetCord/ThreadCurrentUser.cs b/NetCord/ThreadCurrentUser.cs index a1e0731e1..797f06955 100644 --- a/NetCord/ThreadCurrentUser.cs +++ b/NetCord/ThreadCurrentUser.cs @@ -1,9 +1,17 @@ +using NetCord.JsonModels; + namespace NetCord; -public class ThreadCurrentUser(JsonModels.JsonThreadCurrentUser jsonModel) : IJsonModel +/// +/// A minimal , sent for threads within the event. +/// +public class ThreadCurrentUser(JsonThreadCurrentUser jsonModel) : IJsonModel { - JsonModels.JsonThreadCurrentUser IJsonModel.JsonModel => jsonModel; + JsonThreadCurrentUser IJsonModel.JsonModel => jsonModel; + /// public DateTimeOffset JoinTimestamp => jsonModel.JoinTimestamp; + + /// public int Flags => jsonModel.Flags; } diff --git a/NetCord/ThreadUser.cs b/NetCord/ThreadUser.cs index bc9867e1a..178b5b0c4 100644 --- a/NetCord/ThreadUser.cs +++ b/NetCord/ThreadUser.cs @@ -1,14 +1,33 @@ +using NetCord.JsonModels; using NetCord.Rest; namespace NetCord; -public class ThreadUser(JsonModels.JsonThreadUser jsonModel, RestClient client) : ClientEntity(client), ISpanFormattable, IJsonModel +/// +/// Represents a user that has joined a thread. +/// +public class ThreadUser(JsonThreadUser jsonModel, RestClient client) : ClientEntity(client), ISpanFormattable, IJsonModel { - JsonModels.JsonThreadUser IJsonModel.JsonModel => jsonModel; + JsonThreadUser IJsonModel.JsonModel => jsonModel; + /// + /// The thread user's ID. + /// public override ulong Id => jsonModel.UserId; + + /// + /// The ID corresponding to the joined thread. + /// public ulong ThreadId => jsonModel.ThreadId; + + /// + /// The timetstamp at which the user last joined the thread. + /// public DateTimeOffset JoinTimestamp => jsonModel.JoinTimestamp; + + /// + /// The user's thread settings, currently only used for notifications. + /// public int Flags => jsonModel.Flags; public override string ToString() => $"<@{Id}>"; diff --git a/NetCord/User.cs b/NetCord/User.cs index d9223c426..6bbaed300 100644 --- a/NetCord/User.cs +++ b/NetCord/User.cs @@ -221,7 +221,7 @@ public User(JsonModels.JsonUser jsonModel, RestClient client) : base(client) /// /// Gets the of the user's avatar. /// - /// The format of the returned . Defaults to (or for animated avatars). + /// The format of the returned . Defaults to (or for animated avatars). /// An pointing to the user's avatar. If the user does not have one set, returns . public ImageUrl? GetAvatarUrl(ImageFormat? format = null) => AvatarHash is string hash ? ImageUrl.UserAvatar(Id, hash, format) : null; @@ -233,7 +233,7 @@ public User(JsonModels.JsonUser jsonModel, RestClient client) : base(client) /// /// Gets the of the user's banner. /// - /// The format of the returned . Defaults to (or for animated banners). + /// The format of the returned . Defaults to (or for animated banners). /// An pointing to the user's banner. If the user does not have one set, returns . public ImageUrl? GetBannerUrl(ImageFormat? format = null) => BannerHash is string hash ? ImageUrl.UserBanner(Id, hash, format) : null; diff --git a/NetCord/VideoQualityMode.cs b/NetCord/VideoQualityMode.cs index 7a9c7fefc..ce7caef0a 100644 --- a/NetCord/VideoQualityMode.cs +++ b/NetCord/VideoQualityMode.cs @@ -1,14 +1,22 @@ namespace NetCord; +/// +/// Determines Discord's behaviour towards video quality optimization. +/// public enum VideoQualityMode { + /// + /// No video quality mode specified. + /// None = 0, + /// - /// Discord chooses the quality for optimal performance + /// Allows discord to adjust the quality for optimal performance. /// Auto = 1, + /// - /// 720p + /// Locks all video to 720p. /// Full = 2, } diff --git a/NetCord/VoiceAttachment.cs b/NetCord/VoiceAttachment.cs index 0d1846c54..c7aa6914f 100644 --- a/NetCord/VoiceAttachment.cs +++ b/NetCord/VoiceAttachment.cs @@ -1,7 +1,12 @@ using NetCord.JsonModels; +using NetCord.Rest; namespace NetCord; +/// +/// Represents an attachment with properties relevant to voice messages. +/// +/// public class VoiceAttachment(JsonAttachment jsonModel) : Attachment(jsonModel) { /// diff --git a/Tests/MentionTest/TryFormat.cs b/Tests/MentionTest/TryFormat.cs index 8bec51b45..6fc6e9742 100644 --- a/Tests/MentionTest/TryFormat.cs +++ b/Tests/MentionTest/TryFormat.cs @@ -31,7 +31,7 @@ public class TryFormat private static readonly IReadOnlyList _timestampFormats = Enum.GetValues().Select(s => (char)s).ToArray(); - private static readonly IReadOnlyList _imageUrls = _ids.Select(id => NetCord.ImageUrl.CustomEmoji(id, ImageFormat.Png)).ToArray(); + private static readonly IReadOnlyList _imageUrls = _ids.Select(id => NetCord.ImageUrl.CustomEmoji(id, ImageFormat.PNG)).ToArray(); private static readonly IReadOnlyList _imageUrlSizes = ["16", "32", "64", "128", "256", "512", "1024", "2048", "4096"]; diff --git a/Tests/NetCord.Test/Commands/StrangeCommands.cs b/Tests/NetCord.Test/Commands/StrangeCommands.cs index f0833f263..0bf2dad17 100644 --- a/Tests/NetCord.Test/Commands/StrangeCommands.cs +++ b/Tests/NetCord.Test/Commands/StrangeCommands.cs @@ -209,7 +209,7 @@ public Task BotAvatar() public async Task BotAvatar(Uri avatarUrl) { var a = await new HttpClient().GetByteArrayAsync(avatarUrl); - await Context.Client.Cache.User!.ModifyAsync(p => p.Avatar = new ImageProperties(ImageFormat.Png, a)); + await Context.Client.Cache.User!.ModifyAsync(p => p.Avatar = new ImageProperties(ImageFormat.PNG, a)); } [Command("spam")] From 1879a5983e4d0d052b8eca93af66c060036a464f Mon Sep 17 00:00:00 2001 From: Red-K0 <114494949+Red-K0@users.noreply.github.com> Date: Sat, 18 Jul 2026 04:02:51 +0300 Subject: [PATCH 2/2] Additional documention to prepare for PR. --- NetCord/Application.cs | 49 ++++++++++--------- NetCord/ApplicationEventWebhooksStatus.cs | 3 ++ NetCord/ApplicationFlags.cs | 47 +++++++++++++++--- NetCord/ApplicationInstallParams.cs | 7 ++- NetCord/ApplicationIntegrationType.cs | 7 ++- ...ApplicationIntegrationTypeConfiguration.cs | 5 +- NetCord/ChannelFlags.cs | 7 ++- NetCord/Channels/CategoryGuildChannel.cs | 6 +++ NetCord/Channels/IInteractionChannel.cs | 6 +++ NetCord/Channels/IUnknownChannel.cs | 2 +- NetCord/Channels/TextChannels/DMChannel.cs | 6 +++ .../Channels/TextChannels/GroupDMChannel.cs | 22 +++++++++ .../Guild/MediaForumGuildChannel.cs | 3 ++ .../TextChannels/IUnknownDMChannel.cs | 3 ++ .../TextChannels/IUnknownTextChannel.cs | 3 ++ NetCord/Channels/TextChannels/TextChannel.cs | 10 ++++ .../Channels/TextChannels/UnknownDMChannel.cs | 1 + .../TextChannels/UnknownTextChannel.cs | 1 + NetCord/Channels/UnknownChannel.cs | 1 + NetCord/Channels/UnknownGuildChannel.cs | 1 + .../VoiceChannels/Guild/IVoiceGuildChannel.cs | 24 +++++++++ .../VoiceChannels/Guild/StageGuildChannel.cs | 6 +++ .../VoiceChannels/Guild/VoiceGuildChannel.cs | 4 ++ NetCord/CurrentApplication.cs | 3 ++ NetCord/CustomEmoji.cs | 5 +- NetCord/Gateway/UserActivityFlags.cs | 11 +++++ NetCord/JsonModels/JsonTeamUser.cs | 2 +- NetCord/JsonModels/JsonThreadCurrentUser.cs | 2 +- NetCord/MembershipState.cs | 10 ++++ NetCord/PremiumType.cs | 18 +++++++ .../ApplicationInstallParamsProperties.cs | 3 ++ ...nIntegrationTypeConfigurationProperties.cs | 2 + NetCord/Rest/CurrentApplicationOptions.cs | 20 ++++++++ NetCord/Rest/ImageProperties.cs | 8 +-- NetCord/Rest/Sku.cs | 13 +++-- NetCord/Rest/SkuFlags.cs | 33 +++++++++++++ NetCord/Rest/SkuType.cs | 5 +- NetCord/Rest/SystemChannelFlags.cs | 3 ++ NetCord/Team.cs | 23 +++++++++ NetCord/TeamRole.cs | 14 ++++-- NetCord/TeamUser.cs | 8 +-- NetCord/ThreadCurrentUser.cs | 2 +- NetCord/ThreadUser.cs | 2 +- NetCord/ThreadUserFlags.cs | 33 +++++++++++++ NetCord/UserFlags.cs | 13 +++-- 45 files changed, 391 insertions(+), 66 deletions(-) create mode 100644 NetCord/ThreadUserFlags.cs diff --git a/NetCord/Application.cs b/NetCord/Application.cs index 835e9cd31..295a3cb31 100644 --- a/NetCord/Application.cs +++ b/NetCord/Application.cs @@ -45,42 +45,42 @@ public Application(JsonModels.JsonApplication jsonModel, RestClient client) : ba } /// - /// The ID of the application. + /// The application's ID.. /// public override ulong Id => _jsonModel.Id; /// - /// The name of the application. + /// The application's name. /// public string Name => _jsonModel.Name; /// - /// The icon hash of the application. + /// The application's icon hash. /// public string? IconHash => _jsonModel.IconHash; /// - /// The description of the application. + /// The application's description. /// public string Description => _jsonModel.Description; /// - /// A list of the application's RPC origin URLs. if RPC is disabled. + /// A list of the application's RPC origin URLs if enabled, otherwise . /// public IReadOnlyList RpcOrigins => _jsonModel.RpcOrigins; /// - /// When , only the application owner can add the application to guilds. + /// Whether users other than the owner can add the application to guilds. /// public bool? BotPublic => _jsonModel.BotPublic; /// - /// When , the application's bot will only join upon completion of the full OAuth2 code grant flow. + /// Whether the application's bot will only join upon completion of the full OAuth2 code grant flow. /// public bool? BotRequireCodeGrant => _jsonModel.BotRequireCodeGrant; /// - /// The partial object of the application's bot. + /// The application's user object, representing its bot. /// public User? Bot { get; } @@ -95,42 +95,42 @@ public Application(JsonModels.JsonApplication jsonModel, RestClient client) : ba public string? PrivacyPolicyUrl => _jsonModel.PrivacyPolicyUrl; /// - /// The partial object of the application's owner. + /// The application owner's user object. /// public User? Owner { get; } /// - /// The hex-encoded verification key used for HTTP interactions and the GameSDK's GetTicket. + /// A hex-encoded verification key, used for HTTP interactions and the GameSDK's GetTicket endpoint. /// public string VerifyKey => _jsonModel.VerifyKey; /// - /// The team the application belongs to. Is if the application does not belong to a team. + /// The team the application belongs to, if any. /// public Team? Team { get; } /// - /// The ID of the guild associated with the application. For example, a developer support server. + /// The ID corresponding to the application's guild. /// public ulong? GuildId => _jsonModel.GuildId; /// - /// The partial object of the application's associated guild. + /// The application guild's object. /// public RestGuild? Guild { get; } /// - /// The ID of the Game SKU created, if one exists. Is if the application is not a game sold on Discord. + /// The ID of the appliication's Game SKU if it exists, otherwise . /// public ulong? PrimarySkuId => _jsonModel.PrimarySkuId; /// - /// The URL slug that links to an application's store page. Is if the application is not a game sold on Discord. + /// The URL slug that links to an application's store pageif it exists, otherwise . /// public string? Slug => _jsonModel.Slug; /// - /// The cover image hash of the application's default rich presence invite. + /// The cover image hash for the application's default rich presence invite. /// public string? CoverImageHash => _jsonModel.CoverImageHash; @@ -150,7 +150,7 @@ public Application(JsonModels.JsonApplication jsonModel, RestClient client) : ba public int? ApproximateUserInstallCount => _jsonModel.ApproximateUserInstallCount; /// - /// The application's redirect URI list. + /// A list of the application's redirect URIs. /// public IReadOnlyList? RedirectUris => _jsonModel.RedirectUris; @@ -170,32 +170,35 @@ public Application(JsonModels.JsonApplication jsonModel, RestClient client) : ba public string? EventWebhooksUrl => _jsonModel.EventWebhooksUrl; /// - /// The application's event webhooks status. + /// The application's configuration for webhook events. /// public ApplicationEventWebhooksStatus EventWebhooksStatus => _jsonModel.EventWebhooksStatus; /// - /// The list of event webhook types that the application supports. + /// A list of event webhook types that the application supports. /// public IReadOnlyList? EventWebhooksTypes => _jsonModel.EventWebhooksTypes; /// - /// The application's tag list, describing its content and functionality. Max of 5 tags. + /// A list of the application's tags, describing its content and functionality. /// + /// + /// A maximum of 5 tags is supported. + /// public IReadOnlyList? Tags => _jsonModel.Tags; /// - /// The application's default in-app authorization URL. Is if disabled. + /// The application's default in-app authorization URL if enabled, otherwise . /// public ApplicationInstallParams? InstallParams { get; } /// - /// The default scopes and permissions for each supported installation context. + /// A list of the app's default scopes and permissions, for each supported installation context. /// public IReadOnlyDictionary? IntegrationTypesConfiguration { get; } /// - /// The application's default custom install URL. Is if disabled. + /// The application's default custom install URL if enabled, otherwise . /// public string? CustomInstallUrl => _jsonModel.CustomInstallUrl; diff --git a/NetCord/ApplicationEventWebhooksStatus.cs b/NetCord/ApplicationEventWebhooksStatus.cs index a027341d2..d36e764a2 100644 --- a/NetCord/ApplicationEventWebhooksStatus.cs +++ b/NetCord/ApplicationEventWebhooksStatus.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Specifies an application's configuration for webhook events. +/// public enum ApplicationEventWebhooksStatus { /// diff --git a/NetCord/ApplicationFlags.cs b/NetCord/ApplicationFlags.cs index a8c940976..9277a8dc0 100644 --- a/NetCord/ApplicationFlags.cs +++ b/NetCord/ApplicationFlags.cs @@ -2,36 +2,59 @@ namespace NetCord; +/// +/// Specifies the capabilities and status of an app. +/// [Flags] public enum ApplicationFlags : uint { /// - /// Undocumented. + /// Indicates if an embedded app is available to play. /// EmbeddedReleased = 1 << 1, /// - /// Undocumented. + /// Indicates if an app has the ability to create twitch-style emoji. /// ManagedEmoji = 1 << 2, /// - /// Undocumented. + /// Indicates that an embedded app has the ability to create in-app purchases. /// - EmbeddedIAP = 1 << 3, + EmbeddedInAppPurchases = 1 << 3, /// - /// Undocumented. + /// Indicates if an app has permission to create group DMs. /// GroupDMCreate = 1 << 4, + /// + /// Allows the application access the local RPC server. + /// + RpcPrivateBeta = 1 << 5, + /// /// Indicates if an app uses the Auto Moderation API. /// ApplicationAutoModerationRuleCreateBadge = 1 << 6, /// - /// Undocumented. + /// Indicates if an app is allowed to create activity assets. + /// + AllowAssets = 1 << 8, + + /// + /// Indicates if an app is allowed to enable activity spectating. + /// + AllowActivityActionSpectate = 1 << 9, + + /// + /// Indicates if an app is allowed to enable join requests for activities. + /// + AllowActivityActionJoinRequest = 1 << 10, + + /// + /// Indiicates whether an app has ever accessed the local RPC server. /// RPCHasConnected = 1 << 11, @@ -76,7 +99,7 @@ public enum ApplicationFlags : uint GatewayMessageContentLimited = 1 << 19, /// - /// Undocumented. + /// Indicates a first-party embedded app. /// EmbeddedFirstParty = 1 << 20, @@ -84,4 +107,14 @@ public enum ApplicationFlags : uint /// Indicates if an app has registered global application commands. /// ApplicationCommandBadge = 1 << 23, + + /// + /// Indicates if an app is considered active. + /// + Active = 1 << 24, + + /// + /// Indiciates if an app is allowed to use IFrame modals. + /// + IFrameModal = 1 << 26, } diff --git a/NetCord/ApplicationInstallParams.cs b/NetCord/ApplicationInstallParams.cs index c375280b7..dd6552ed0 100644 --- a/NetCord/ApplicationInstallParams.cs +++ b/NetCord/ApplicationInstallParams.cs @@ -2,17 +2,20 @@ namespace NetCord; +/// +/// Represents the configuration state for an application install. +/// public class ApplicationInstallParams(JsonApplicationInstallParams jsonModel) : IJsonModel { JsonApplicationInstallParams IJsonModel.JsonModel => jsonModel; /// - /// Scopes to add the application to the server with. + /// The scopes to use when installing the application to the guild. /// public IReadOnlyList Scopes => jsonModel.Scopes; /// - /// Permissions to request for the bot role. + /// The permissions to request for the application's bot role. /// public Permissions Permissions => jsonModel.Permissions; } diff --git a/NetCord/ApplicationIntegrationType.cs b/NetCord/ApplicationIntegrationType.cs index d3d865ebb..b1a067a54 100644 --- a/NetCord/ApplicationIntegrationType.cs +++ b/NetCord/ApplicationIntegrationType.cs @@ -1,14 +1,17 @@ namespace NetCord; +/// +/// Represents an app integration's install type. +/// public enum ApplicationIntegrationType { /// - /// App is installable to servers. + /// App is available for guild installs. /// GuildInstall = 0, /// - /// App is installable to users. + /// App is available for user installs. /// UserInstall = 1, } diff --git a/NetCord/ApplicationIntegrationTypeConfiguration.cs b/NetCord/ApplicationIntegrationTypeConfiguration.cs index 40fcdb7f5..877de929b 100644 --- a/NetCord/ApplicationIntegrationTypeConfiguration.cs +++ b/NetCord/ApplicationIntegrationTypeConfiguration.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents additional configuration for a specific app installation context. +/// public class ApplicationIntegrationTypeConfiguration : IJsonModel { private readonly JsonApplicationIntegrationTypeConfiguration _jsonModel; @@ -17,7 +20,7 @@ public ApplicationIntegrationTypeConfiguration(JsonApplicationIntegrationTypeCon } /// - /// Install params for each installation context's default in-app authorization link. + /// Additional installation params to apply to the specific install context. /// public ApplicationInstallParams? OAuth2InstallParams { get; } } diff --git a/NetCord/ChannelFlags.cs b/NetCord/ChannelFlags.cs index 0dd653fa8..f4e89c77c 100644 --- a/NetCord/ChannelFlags.cs +++ b/NetCord/ChannelFlags.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Represents additional information about a channel's state. +/// [Flags] public enum ChannelFlags { @@ -49,12 +52,12 @@ public enum ChannelFlags MediaChannel = 1 << 10, /// - /// Channel is exempt from 'For You' summaries. + /// Channel is exempt from AI-powered summaries. /// SummariesDisabled = 1 << 11, /// - /// + /// Private channel's recipients consented to the application shelf. /// ApplicationShelfConsent = 1 << 12, diff --git a/NetCord/Channels/CategoryGuildChannel.cs b/NetCord/Channels/CategoryGuildChannel.cs index 39daeae8a..9d30739ec 100644 --- a/NetCord/Channels/CategoryGuildChannel.cs +++ b/NetCord/Channels/CategoryGuildChannel.cs @@ -2,10 +2,16 @@ namespace NetCord; +/// +/// Represents a category within a guild. +/// public partial class CategoryGuildChannel(JsonModels.JsonChannel jsonModel, ulong guildId, RestClient client) : Channel(jsonModel, client), IGuildChannel { public ulong GuildId { get; } = guildId; + public int? Position => _jsonModel.Position; + public IReadOnlyDictionary PermissionOverwrites { get; } = jsonModel.PermissionOverwrites.ToDictionaryOrEmpty(p => p.Id, p => new PermissionOverwrite(p)); + public string Name => _jsonModel.Name!; } diff --git a/NetCord/Channels/IInteractionChannel.cs b/NetCord/Channels/IInteractionChannel.cs index 8c62916f8..353e8c17d 100644 --- a/NetCord/Channels/IInteractionChannel.cs +++ b/NetCord/Channels/IInteractionChannel.cs @@ -1,7 +1,13 @@ namespace NetCord; +/// +/// An optional interface for acquiring channel permissions. +/// public interface IInteractionChannel : IEntity, ISpanFormattable { + /// + /// The chan + /// public Permissions Permissions { get; } public string ToString(); diff --git a/NetCord/Channels/IUnknownChannel.cs b/NetCord/Channels/IUnknownChannel.cs index b121e9554..98b7f1045 100644 --- a/NetCord/Channels/IUnknownChannel.cs +++ b/NetCord/Channels/IUnknownChannel.cs @@ -6,7 +6,7 @@ namespace NetCord; public interface IUnknownChannel : IEntity, ISpanFormattable { /// - /// The type of the unresolved channel. + /// The unresolved channel's type. /// public ChannelType Type { get; } } diff --git a/NetCord/Channels/TextChannels/DMChannel.cs b/NetCord/Channels/TextChannels/DMChannel.cs index bee6e0027..b759480e7 100644 --- a/NetCord/Channels/TextChannels/DMChannel.cs +++ b/NetCord/Channels/TextChannels/DMChannel.cs @@ -2,8 +2,14 @@ namespace NetCord; +/// +/// Represents a text channel for private messages between two users. +/// public partial class DMChannel(JsonModels.JsonChannel jsonModel, RestClient client) : TextChannel(jsonModel, client) { + /// + /// A list of the users present in the private channel, indexed by their IDs. + /// public IReadOnlyDictionary Users { get; } = jsonModel.Users.ToDictionaryOrEmpty(u => u.Id, u => new User(u, client)); public static new DMChannel CreateFromJson(JsonModels.JsonChannel jsonModel, RestClient client) diff --git a/NetCord/Channels/TextChannels/GroupDMChannel.cs b/NetCord/Channels/TextChannels/GroupDMChannel.cs index 8a2bdd8ec..d0474a43d 100644 --- a/NetCord/Channels/TextChannels/GroupDMChannel.cs +++ b/NetCord/Channels/TextChannels/GroupDMChannel.cs @@ -2,11 +2,33 @@ namespace NetCord; +/// +/// Represents a text channel for private messages, with up to 10 users. +/// public partial class GroupDMChannel(JsonModels.JsonChannel jsonModel, RestClient client) : DMChannel(jsonModel, client), INamedChannel { + /// + /// The group channel's name. + /// public string Name => _jsonModel.Name!; + + /// + /// The group channel's icon hash. + /// public string? IconHash => _jsonModel.IconHash; + + /// + /// The ID corresponding to the group channel's owner. + /// public ulong OwnerId => _jsonModel.OwnerId.GetValueOrDefault(); + + /// + /// The ID corresponding to the application managing the group channel, if any, otherwise . + /// public ulong? ApplicationId => _jsonModel.ApplicationId; + + /// + /// Whether the group channel is managed by an application with set. + /// public bool Managed => _jsonModel.Managed.GetValueOrDefault(); } diff --git a/NetCord/Channels/TextChannels/Guild/MediaForumGuildChannel.cs b/NetCord/Channels/TextChannels/Guild/MediaForumGuildChannel.cs index b674a6f8d..a0d5e0a9d 100644 --- a/NetCord/Channels/TextChannels/Guild/MediaForumGuildChannel.cs +++ b/NetCord/Channels/TextChannels/Guild/MediaForumGuildChannel.cs @@ -3,6 +3,9 @@ namespace NetCord; +/// +/// Represents a media channel, which is a specialized . +/// public partial class MediaForumGuildChannel(JsonChannel jsonModel, ulong guildId, RestClient client) : ForumGuildChannel(jsonModel, guildId, client) { } diff --git a/NetCord/Channels/TextChannels/IUnknownDMChannel.cs b/NetCord/Channels/TextChannels/IUnknownDMChannel.cs index 0136c0aa4..60e5821cf 100644 --- a/NetCord/Channels/TextChannels/IUnknownDMChannel.cs +++ b/NetCord/Channels/TextChannels/IUnknownDMChannel.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Represents a channel for private messages of an unresolved type. +/// public interface IUnknownDMChannel : IUnknownTextChannel { } diff --git a/NetCord/Channels/TextChannels/IUnknownTextChannel.cs b/NetCord/Channels/TextChannels/IUnknownTextChannel.cs index 0f10409d8..f96d5f338 100644 --- a/NetCord/Channels/TextChannels/IUnknownTextChannel.cs +++ b/NetCord/Channels/TextChannels/IUnknownTextChannel.cs @@ -1,5 +1,8 @@ namespace NetCord; +/// +/// Represents a text channel of an unresolved type. +/// public interface IUnknownTextChannel : IUnknownChannel { } diff --git a/NetCord/Channels/TextChannels/TextChannel.cs b/NetCord/Channels/TextChannels/TextChannel.cs index 6b2373e97..750825000 100644 --- a/NetCord/Channels/TextChannels/TextChannel.cs +++ b/NetCord/Channels/TextChannels/TextChannel.cs @@ -3,9 +3,19 @@ namespace NetCord; +/// +/// Represents a generic text channel. +/// public abstract partial class TextChannel(JsonChannel jsonModel, RestClient client) : Channel(jsonModel, client) { + /// + /// The ID corresponding to the last message sent within the channel. Can be if the channel is empty. + /// public ulong? LastMessageId => _jsonModel.LastMessageId; + + /// + /// The timestamp of the last pinned message, if any, otherwise . + /// public DateTimeOffset? LastPin => _jsonModel.LastPin; public static new TextChannel CreateFromJson(JsonChannel jsonChannel, RestClient client) diff --git a/NetCord/Channels/TextChannels/UnknownDMChannel.cs b/NetCord/Channels/TextChannels/UnknownDMChannel.cs index 65ffe1f46..c3c193623 100644 --- a/NetCord/Channels/TextChannels/UnknownDMChannel.cs +++ b/NetCord/Channels/TextChannels/UnknownDMChannel.cs @@ -2,6 +2,7 @@ namespace NetCord; +/// internal partial class UnknownDMChannel(JsonModels.JsonChannel jsonModel, RestClient client) : DMChannel(jsonModel, client), IUnknownDMChannel { public ChannelType Type => _jsonModel.Type; diff --git a/NetCord/Channels/TextChannels/UnknownTextChannel.cs b/NetCord/Channels/TextChannels/UnknownTextChannel.cs index 6eb5744b4..015850702 100644 --- a/NetCord/Channels/TextChannels/UnknownTextChannel.cs +++ b/NetCord/Channels/TextChannels/UnknownTextChannel.cs @@ -3,6 +3,7 @@ namespace NetCord; +/// internal partial class UnknownTextChannel(JsonChannel jsonModel, RestClient client) : TextChannel(jsonModel, client), IUnknownTextChannel { public ChannelType Type => _jsonModel.Type; diff --git a/NetCord/Channels/UnknownChannel.cs b/NetCord/Channels/UnknownChannel.cs index a89052efb..228f42290 100644 --- a/NetCord/Channels/UnknownChannel.cs +++ b/NetCord/Channels/UnknownChannel.cs @@ -3,6 +3,7 @@ namespace NetCord; +/// internal partial class UnknownChannel(JsonChannel jsonModel, RestClient client) : Channel(jsonModel, client), IUnknownChannel { public ChannelType Type => _jsonModel.Type; diff --git a/NetCord/Channels/UnknownGuildChannel.cs b/NetCord/Channels/UnknownGuildChannel.cs index abb8539e7..dbff4b343 100644 --- a/NetCord/Channels/UnknownGuildChannel.cs +++ b/NetCord/Channels/UnknownGuildChannel.cs @@ -3,6 +3,7 @@ namespace NetCord; +/// internal partial class UnknownGuildChannel(JsonChannel jsonModel, ulong guildId, RestClient client) : UnknownChannel(jsonModel, client), IUnknownGuildChannel { public ulong GuildId { get; } = guildId; diff --git a/NetCord/Channels/VoiceChannels/Guild/IVoiceGuildChannel.cs b/NetCord/Channels/VoiceChannels/Guild/IVoiceGuildChannel.cs index 7852886dc..82bc7ddf6 100644 --- a/NetCord/Channels/VoiceChannels/Guild/IVoiceGuildChannel.cs +++ b/NetCord/Channels/VoiceChannels/Guild/IVoiceGuildChannel.cs @@ -1,12 +1,36 @@ namespace NetCord; +/// +/// Represents a voice channel within a guild. +/// public partial interface IVoiceGuildChannel : IGuildChannel { + /// public bool Nsfw { get; } + + /// + /// The voice channel's bitrate (in bits per second). + /// public int Bitrate { get; } + + /// + /// The voice channel's user limit. + /// public int UserLimit { get; } + + /// public int Slowmode { get; } + + /// public ulong? ParentId { get; } + + /// + /// The voice channel's preferred region, if set. When , Discord automatically determines this. + /// public string? RtcRegion { get; } + + /// + /// The voice channel's video optimization mode (for cameras). + /// public VideoQualityMode VideoQualityMode { get; } } diff --git a/NetCord/Channels/VoiceChannels/Guild/StageGuildChannel.cs b/NetCord/Channels/VoiceChannels/Guild/StageGuildChannel.cs index a573fb9aa..57453aef6 100644 --- a/NetCord/Channels/VoiceChannels/Guild/StageGuildChannel.cs +++ b/NetCord/Channels/VoiceChannels/Guild/StageGuildChannel.cs @@ -2,10 +2,16 @@ namespace NetCord; +/// +/// Represents a stage channel within a guild. +/// public partial class StageGuildChannel(JsonModels.JsonChannel jsonModel, ulong guildId, RestClient client) : TextGuildChannel(jsonModel, guildId, client), IVoiceGuildChannel { public int Bitrate => _jsonModel.Bitrate.GetValueOrDefault(); + public int UserLimit => _jsonModel.UserLimit.GetValueOrDefault(); + public string? RtcRegion => _jsonModel.RtcRegion; + public VideoQualityMode VideoQualityMode => _jsonModel.VideoQualityMode.GetValueOrDefault(VideoQualityMode.Auto); } diff --git a/NetCord/Channels/VoiceChannels/Guild/VoiceGuildChannel.cs b/NetCord/Channels/VoiceChannels/Guild/VoiceGuildChannel.cs index 559fedb8d..23e9af3f2 100644 --- a/NetCord/Channels/VoiceChannels/Guild/VoiceGuildChannel.cs +++ b/NetCord/Channels/VoiceChannels/Guild/VoiceGuildChannel.cs @@ -2,10 +2,14 @@ namespace NetCord; +/// public partial class VoiceGuildChannel(JsonModels.JsonChannel jsonModel, ulong guildId, RestClient client) : TextGuildChannel(jsonModel, guildId, client), IVoiceGuildChannel { public int Bitrate => _jsonModel.Bitrate.GetValueOrDefault(); + public int UserLimit => _jsonModel.UserLimit.GetValueOrDefault(); + public string? RtcRegion => _jsonModel.RtcRegion; + public VideoQualityMode VideoQualityMode => _jsonModel.VideoQualityMode.GetValueOrDefault(VideoQualityMode.Auto); } diff --git a/NetCord/CurrentApplication.cs b/NetCord/CurrentApplication.cs index b185dbacf..bf4f242cc 100644 --- a/NetCord/CurrentApplication.cs +++ b/NetCord/CurrentApplication.cs @@ -2,6 +2,9 @@ namespace NetCord; +/// +/// Represents a bot's current . +/// public partial class CurrentApplication(JsonModels.JsonApplication jsonModel, RestClient client) : Application(jsonModel, client) { } diff --git a/NetCord/CustomEmoji.cs b/NetCord/CustomEmoji.cs index 254fa2510..b06589549 100644 --- a/NetCord/CustomEmoji.cs +++ b/NetCord/CustomEmoji.cs @@ -35,8 +35,11 @@ public CustomEmoji(JsonEmoji jsonModel, RestClient client) : base(jsonModel) public bool? RequireColons => _jsonModel.RequireColons; /// - /// Whether the emoji is managed. + /// Whether the emoji is managed by an application. /// + /// + /// Managed emoji can only be created by apps with the flag set. + /// public bool? Managed => _jsonModel.Managed; /// diff --git a/NetCord/Gateway/UserActivityFlags.cs b/NetCord/Gateway/UserActivityFlags.cs index 289daf18b..34b996713 100644 --- a/NetCord/Gateway/UserActivityFlags.cs +++ b/NetCord/Gateway/UserActivityFlags.cs @@ -1,15 +1,26 @@ namespace NetCord.Gateway; +/// +/// Flags about an activity's state. Not current documented. +/// [Flags] public enum UserActivityFlags { Instance = 1 << 0, + Join = 1 << 1, + Spectate = 1 << 2, + JoinRequest = 1 << 3, + Sync = 1 << 4, + Play = 1 << 5, + PartyPrivacyFriends = 1 << 6, + PartyPrivacyVoiceChannel = 1 << 7, + Embedded = 1 << 8, } diff --git a/NetCord/JsonModels/JsonTeamUser.cs b/NetCord/JsonModels/JsonTeamUser.cs index f2ac5bcdd..2c032550c 100644 --- a/NetCord/JsonModels/JsonTeamUser.cs +++ b/NetCord/JsonModels/JsonTeamUser.cs @@ -9,7 +9,7 @@ public class JsonTeamUser [JsonPropertyName("team_id")] public ulong TeamId { get; set; } - + [JsonPropertyName("user")] public JsonUser User { get; set; } diff --git a/NetCord/JsonModels/JsonThreadCurrentUser.cs b/NetCord/JsonModels/JsonThreadCurrentUser.cs index 4dbc4e128..33463f378 100644 --- a/NetCord/JsonModels/JsonThreadCurrentUser.cs +++ b/NetCord/JsonModels/JsonThreadCurrentUser.cs @@ -8,5 +8,5 @@ public class JsonThreadCurrentUser public DateTimeOffset JoinTimestamp { get; set; } [JsonPropertyName("flags")] - public int Flags { get; set; } + public ThreadUserFlags Flags { get; set; } } diff --git a/NetCord/MembershipState.cs b/NetCord/MembershipState.cs index b1552e139..08cae555c 100644 --- a/NetCord/MembershipState.cs +++ b/NetCord/MembershipState.cs @@ -1,7 +1,17 @@ namespace NetCord; +/// +/// Specifies a 's state, relative to a team. +/// public enum MembershipState { + /// + /// The user has been invited to the team, but has not yet accepted or declined. + /// Invited = 1, + + /// + /// The user has accepted a team invitation, and is a member of the team. + /// Accepted = 2, } diff --git a/NetCord/PremiumType.cs b/NetCord/PremiumType.cs index 8796d2b1b..af3e223e9 100644 --- a/NetCord/PremiumType.cs +++ b/NetCord/PremiumType.cs @@ -1,9 +1,27 @@ namespace NetCord; +/// +/// Specifies a Nitro subscription's type. +/// public enum PremiumType { + /// + /// No current Nitro subscription. + /// None = 0, + + /// + /// A Nitro Classic subscription. + /// NitroClassic = 1, + + /// + /// A standard Nitro subscription. + /// Nitro = 2, + + /// + /// A Nitro Basic subscription. + /// NitroBasic = 3, } diff --git a/NetCord/Rest/ApplicationInstallParamsProperties.cs b/NetCord/Rest/ApplicationInstallParamsProperties.cs index 2c1043510..820f6818c 100644 --- a/NetCord/Rest/ApplicationInstallParamsProperties.cs +++ b/NetCord/Rest/ApplicationInstallParamsProperties.cs @@ -2,13 +2,16 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class ApplicationInstallParamsProperties { + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("scopes")] public IEnumerable? Scopes { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("permissions")] public Permissions? Permissions { get; set; } diff --git a/NetCord/Rest/ApplicationIntegrationTypeConfigurationProperties.cs b/NetCord/Rest/ApplicationIntegrationTypeConfigurationProperties.cs index fbbf2cfa6..4591dce97 100644 --- a/NetCord/Rest/ApplicationIntegrationTypeConfigurationProperties.cs +++ b/NetCord/Rest/ApplicationIntegrationTypeConfigurationProperties.cs @@ -2,9 +2,11 @@ namespace NetCord.Rest; +/// [GenerateMethodsForProperties] public partial class ApplicationIntegrationTypeConfigurationProperties { + /// [JsonPropertyName("oauth2_install_params")] public ApplicationInstallParamsProperties? OAuth2InstallParams { get; set; } } diff --git a/NetCord/Rest/CurrentApplicationOptions.cs b/NetCord/Rest/CurrentApplicationOptions.cs index 9659d3860..57bde2e37 100644 --- a/NetCord/Rest/CurrentApplicationOptions.cs +++ b/NetCord/Rest/CurrentApplicationOptions.cs @@ -2,6 +2,9 @@ namespace NetCord.Rest; +/// +/// Represents a modification to apply to the bot user's current application. +/// [GenerateMethodsForProperties] public partial class CurrentApplicationOptions { @@ -9,54 +12,71 @@ internal CurrentApplicationOptions() { } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("custom_install_url")] public string? CustomInstallUrl { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("description")] public string? Description { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("role_connections_verification_url")] public string? RoleConnectionsVerificationUrl { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("install_params")] public ApplicationInstallParamsProperties? InstallParams { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("integration_types_config")] public IReadOnlyDictionary? IntegrationTypesConfiguration { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("flags")] public ApplicationFlags? Flags { get; set; } + /// + /// The application's icon. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("icon")] public ImageProperties? Icon { get; set; } + /// + /// The application's cover image. + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("cover_image")] public ImageProperties? CoverImage { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("interactions_endpoint_url")] public string? InteractionsEndpointUrl { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("tags")] public IEnumerable? Tags { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("event_webhooks_url")] public string? EventWebhooksUrl { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("event_webhooks_status")] public ApplicationEventWebhooksStatus? EventWebhooksStatus { get; set; } + /// [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] [JsonPropertyName("event_webhooks_types")] public IEnumerable? EventWebhooksTypes { get; set; } diff --git a/NetCord/Rest/ImageProperties.cs b/NetCord/Rest/ImageProperties.cs index dcbc7b81e..e44ad7e61 100644 --- a/NetCord/Rest/ImageProperties.cs +++ b/NetCord/Rest/ImageProperties.cs @@ -8,7 +8,7 @@ namespace NetCord.Rest; /// -/// +/// Represents an image. /// /// The format of the image. /// The data of the image. @@ -18,17 +18,17 @@ namespace NetCord.Rest; public partial struct ImageProperties(ImageFormat format, ReadOnlyMemory data, bool isBase64 = false) { /// - /// The format of the image. + /// The image's format. /// public ImageFormat Format { get; set; } = format; /// - /// The data of the image. + /// The image's contents, represented as a block of bytes. /// public ReadOnlyMemory Data { get; set; } = data; /// - /// Whether is in Base64 format. + /// Whether the contents of are encoded in Base64. /// public bool IsBase64 { get; set; } = isBase64; diff --git a/NetCord/Rest/Sku.cs b/NetCord/Rest/Sku.cs index e33aaf7f3..eba6a355f 100644 --- a/NetCord/Rest/Sku.cs +++ b/NetCord/Rest/Sku.cs @@ -1,5 +1,8 @@ namespace NetCord.Rest; +/// +/// Represents a premium offering that can be made to application users/guilds. +/// public partial class Sku(JsonModels.JsonSku jsonModel, RestClient client) : ClientEntity(client), IJsonModel { JsonModels.JsonSku IJsonModel.JsonModel => jsonModel; @@ -7,27 +10,27 @@ public partial class Sku(JsonModels.JsonSku jsonModel, RestClient client) : Clie public override ulong Id => jsonModel.Id; /// - /// Type of the SKU. + /// The SKU's purchase type. /// public SkuType Type => jsonModel.Type; /// - /// ID of the parent application. + /// The ID corresponding to the SKU's parent application. /// public ulong ApplicationId => jsonModel.ApplicationId; /// - /// Customer-facing name of your premium offering. + /// The SKU's customer-facing name. /// public string Name => jsonModel.Name; /// - /// System-generated URL slug based on the SKU's name. + /// The system-generated URL slug, based on the SKU's name. /// public string Slug => jsonModel.Slug; /// - /// Flags of the SKU. + /// The SKU's content flags. /// public SkuFlags Flags => jsonModel.Flags; } diff --git a/NetCord/Rest/SkuFlags.cs b/NetCord/Rest/SkuFlags.cs index 26d817123..18d983b79 100644 --- a/NetCord/Rest/SkuFlags.cs +++ b/NetCord/Rest/SkuFlags.cs @@ -1,13 +1,46 @@ namespace NetCord.Rest; +/// +/// Specifies additional information about an SKU's contents. +/// [Flags] public enum SkuFlags { + /// + /// Whether the SKU is a premium purchase. + /// + PremiumPurchase = 1 << 0, + + /// + /// Whether the SKU is free premium content. + /// + HasFreePremiumContent = 1 << 1, + /// /// SKU is available for purchase. /// Available = 1 << 2, + /// + /// Whether the SKU is a premium or distribution product. + /// + PremiumAndDistribution = 1 << 3, + + /// + /// Whether the SKU is a premium sticker pack. + /// + StickerPack = 1 << 4, + + /// + /// Whether the SKU is a guild role subscription. + /// + GuildRoleSubscription = 1 << 5, + + /// + /// Whether the SKU is a Discord premium subscription or related first-party product. + /// + PremiumSubscription = 1 << 6, + /// /// Recurring SKU that can be purchased by a user and applied to a single server. Grants access to every user in that server. /// diff --git a/NetCord/Rest/SkuType.cs b/NetCord/Rest/SkuType.cs index 837fbf6de..5ba0e82c4 100644 --- a/NetCord/Rest/SkuType.cs +++ b/NetCord/Rest/SkuType.cs @@ -1,5 +1,8 @@ namespace NetCord.Rest; +/// +/// Specifies an SKU's purchase type. +/// public enum SkuType : byte { /// @@ -18,7 +21,7 @@ public enum SkuType : byte Subscription = 5, /// - /// System-generated group for each SUBSCRIPTION SKU created. + /// System-generated group for each subscription SKU created. /// SubscriptionGroup = 6 } diff --git a/NetCord/Rest/SystemChannelFlags.cs b/NetCord/Rest/SystemChannelFlags.cs index b8b0eb2bb..4fc058dc6 100644 --- a/NetCord/Rest/SystemChannelFlags.cs +++ b/NetCord/Rest/SystemChannelFlags.cs @@ -1,5 +1,8 @@ namespace NetCord.Rest; +/// +/// Represents a system channel's configuration state. +/// [Flags] public enum SystemChannelFlags { diff --git a/NetCord/Team.cs b/NetCord/Team.cs index ea73b55ff..adeced40e 100644 --- a/NetCord/Team.cs +++ b/NetCord/Team.cs @@ -2,19 +2,42 @@ namespace NetCord; +/// +/// Represents a group of developers / Discord users who share access to an application's configuration. +/// public class Team(JsonModels.JsonTeam jsonModel, RestClient client) : Entity, IJsonModel { JsonModels.JsonTeam IJsonModel.JsonModel => jsonModel; + /// + /// The team's unique ID. + /// public override ulong Id => jsonModel.Id; + /// + /// The team's icon image hash. + /// public string? IconHash => jsonModel.IconHash; + /// + /// A list of the team's current members. + /// public IReadOnlyList Users { get; } = jsonModel.Users.SelectOrEmpty(m => new TeamUser(m, client)).ToArray(); + /// + /// The team's name. + /// public string Name => jsonModel.Name; + /// + /// The ID corresponding to the team's owner. + /// public ulong OwnerId => jsonModel.OwnerId; + /// + /// Gets the of the team's icon. + /// + /// The format of the returned . Defaults to (or for animated icons). + /// An pointing to the team's icon. If the user does not have one set, returns . public ImageUrl? GetIconUrl(ImageFormat format) => IconHash is string hash ? ImageUrl.TeamIcon(Id, hash, format) : null; } diff --git a/NetCord/TeamRole.cs b/NetCord/TeamRole.cs index 0e70532cf..e0837067d 100644 --- a/NetCord/TeamRole.cs +++ b/NetCord/TeamRole.cs @@ -3,28 +3,32 @@ namespace NetCord; /// -/// A can have one of four roles (Owner, , , and ), and each role inherits the access of those below it. +/// Represents a 's role within a team, excluding owners, which are represented in the property. /// /// -/// The Owner role is not represented in the enum, as it is not represented in 's field. Instead, owners can be identified using a 's field. They have the most permissive role, and can take destructive, irreversible actions like deleting team-owned apps or the team itself. Teams are limited to 1 owner. +/// Each role inherits the properties of the role below it, in the order of , , . +/// Only owners can take destructive, irreversible actions like deleting team-owned apps or the team itself. Teams are limited to 1 owner. /// [JsonConverter(typeof(JsonConverters.SafeStringEnumConverter))] public enum TeamRole : sbyte { /// - /// Admins have similar access to owners, except they cannot take destructive actions on the team or team-owned apps. + /// Admins have similar access to owners, with the exception of destructive actions, such as deleting applications. /// [JsonPropertyName("admin")] Admin, /// - /// Developers can access information about team-owned apps, like the client secret or public key. They can also take limited actions on team-owned apps, like configuring interaction endpoints or resetting the bot token. s with the role cannot manage the or its users, or take destructive actions on team-owned s. + /// Developers have access to sensitive information, such as client secrets and public keys. + /// They can also take some limited actions, such as configuring interaction endpoints, or resetting bot tokens. + /// Developers cannot manage the team or its members. /// [JsonPropertyName("developer")] Developer, /// - /// Read-only users can access information about a and any team-owned s. Some examples include getting the IDs of applications and exporting payout records. Members can also invite bots associated with team-owned apps that are marked private. + /// Read-only users can access information about a team and its applications, such as application IDs, and payout records. + /// They can also invite private applications. /// [JsonPropertyName("read-only")] ReadOnly, diff --git a/NetCord/TeamUser.cs b/NetCord/TeamUser.cs index fcec74c8b..0e9b28c84 100644 --- a/NetCord/TeamUser.cs +++ b/NetCord/TeamUser.cs @@ -3,24 +3,24 @@ namespace NetCord; /// -/// Represents a user as a part of the team indicated by the . +/// Represents a user that is a member of a team. /// public class TeamUser(JsonModels.JsonTeamUser jsonModel, RestClient client) : User(jsonModel.User, client), IJsonModel { JsonModels.JsonTeamUser IJsonModel.JsonModel => jsonModel; /// - /// The membership state of the . + /// The user's membership state. /// public MembershipState MembershipState => jsonModel.MembershipState; /// - /// The ID of the the belongs to. + /// The ID corresponding to the user's team. /// public ulong TeamId => jsonModel.TeamId; /// - /// The role of the in the associated . + /// The user's role within their team. /// public TeamRole Role => jsonModel.Role; } diff --git a/NetCord/ThreadCurrentUser.cs b/NetCord/ThreadCurrentUser.cs index 797f06955..e1a92b2ca 100644 --- a/NetCord/ThreadCurrentUser.cs +++ b/NetCord/ThreadCurrentUser.cs @@ -13,5 +13,5 @@ public class ThreadCurrentUser(JsonThreadCurrentUser jsonModel) : IJsonModel jsonModel.JoinTimestamp; /// - public int Flags => jsonModel.Flags; + public ThreadUserFlags Flags => jsonModel.Flags; } diff --git a/NetCord/ThreadUser.cs b/NetCord/ThreadUser.cs index 178b5b0c4..38472102a 100644 --- a/NetCord/ThreadUser.cs +++ b/NetCord/ThreadUser.cs @@ -28,7 +28,7 @@ public class ThreadUser(JsonThreadUser jsonModel, RestClient client) : ClientEnt /// /// The user's thread settings, currently only used for notifications. /// - public int Flags => jsonModel.Flags; + public ThreadUserFlags Flags => jsonModel.Flags; public override string ToString() => $"<@{Id}>"; diff --git a/NetCord/ThreadUserFlags.cs b/NetCord/ThreadUserFlags.cs new file mode 100644 index 000000000..39d279dae --- /dev/null +++ b/NetCord/ThreadUserFlags.cs @@ -0,0 +1,33 @@ +namespace NetCord; + +/// +/// Represents a 's state, relative to a thread. +/// +[Flags] +public enum ThreadUserFlags +{ + /// + /// User has had no thread interactions. + /// + None = 0, + + /// + /// User has interacted with the thread. + /// + HasInteracted = 1 << 0, + + /// + /// User receives notifcations for all messages. + /// + AllMessages = 1 << 1, + + /// + /// User recieves notifications only for messages that mention them. + /// + OnlyMentions = 1 << 2, + + /// + /// User does not receive any notifications. + /// + NoMessages = 1 << 3, +} diff --git a/NetCord/UserFlags.cs b/NetCord/UserFlags.cs index 7c3237d33..8a773d762 100644 --- a/NetCord/UserFlags.cs +++ b/NetCord/UserFlags.cs @@ -59,7 +59,7 @@ public enum UserFlags : ulong PremiumEarlySupporter = 1uL << 9, /// - /// User is a team. See . + /// User is a . /// TeamPseudoUser = 1uL << 10, @@ -96,12 +96,12 @@ public enum UserFlags : ulong VerifiedBot = 1uL << 16, /// - /// User has the 'Early Verified Developer' badge. + /// User has the 'Early Verified Bot Developer' badge. /// VerifiedDeveloper = 1uL << 17, /// - /// User has the 'Moderator Program Alumni' badge. + /// User has the 'Moderator Programs Alumni' badge. /// CertifiedModerator = 1uL << 18, @@ -111,7 +111,7 @@ public enum UserFlags : ulong BotHttpInteractions = 1uL << 19, /// - /// Undocumented. User's account is flagged for spamming. + /// Undocumented. User's account is disabled for spamming. /// Spammer = 1uL << 20, @@ -120,6 +120,11 @@ public enum UserFlags : ulong /// DisablePremium = 1uL << 21, + /// + /// User is an active developer. + /// + ActiveDeveloper = 1uL << 22, + /// /// Undocumented and private. User's account has a high global rate limit. ///