feat!: add support for invite target user allowlists and job status (#756)

* feat: add support for invite target user allowlists and job status

Introduces methods and endpoints to manage allowlists of users who can accept invites, including CSV-based and user ID-based updates. Adds the ability to query the processing status of invite target user jobs, updates the invite creation API to support role grants and target user restrictions, and implements supporting types and utilities for these features.

* Rename Values to SelectedValues in checkbox group

Renamed the 'Values' property to 'SelectedValues' in DiscordCheckboxGroupComponent to improve clarity and better reflect its purpose.

* refactor: address code review feedback on invite target users feature (#757)

* Initial plan

* docs: improve documentation and code quality for invite target users

Co-Authored-By: copilot-swe-agent[bot] <[email protected]>

Co-authored-by: Lulalaby <[email protected]>

* fix: prevent memory leak by not resetting internally-created MemoryStream

Co-Authored-By: copilot-swe-agent[bot] <[email protected]>

Co-authored-by: Lulalaby <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Lulalaby <[email protected]>

* Dispose targetUsersCsv streams after use

Added try-catch blocks to dispose the targetUsersCsv streams in CreateChannelInviteAsync and UpdateInviteTargetUsersAsync methods to ensure proper resource cleanup and prevent potential memory leaks.

---------

Co-authored-by: Copilot <[email protected]>

Author: Lulalaby

DisCatSharp/Clients/DiscordClient.cs

@@ -1111,6 +1111,67 @@ public bool TryGetInviteByCode(string code, [NotNullWhen(true)] out DiscordInvit
 		}
 	}
 
+	/// <summary>
+	///     Gets the target users allowed to accept an invite.
+	/// </summary>
+	/// <param name="inviteCode">The invite code.</param>
+	/// <returns>An allowlist of user ids.</returns>
+	/// <exception cref="NotFoundException">Thrown when the invite does not exist.</exception>
+	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
+	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
+	public Task<IReadOnlyList<ulong>> GetInviteTargetUsersAsync(string inviteCode)
+		=> this.ApiClient.GetInviteTargetUsersAsync(inviteCode);
+
+	/// <summary>
+	///     Updates the target users allowed to accept an invite using a CSV stream.
+	/// </summary>
+	/// <param name="inviteCode">The invite code.</param>
+	/// <param name="targetUsersCsv">
+	///     CSV stream containing a single <c>Users</c> column. The CSV must have a header row where the first
+	///     (and only) column header is <c>Users</c>, and each subsequent line must contain exactly one user ID.
+	/// </param>
+	/// <param name="reason">The audit log reason.</param>
+	/// <exception cref="NotFoundException">Thrown when the invite does not exist.</exception>
+	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
+	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
+	public Task UpdateInviteTargetUsersAsync(string inviteCode, Stream targetUsersCsv, string reason = null)
+		=> this.ApiClient.UpdateInviteTargetUsersAsync(inviteCode, targetUsersCsv, null, null, reason);
+
+	/// <summary>
+	///     Updates the target users allowed to accept an invite using user ids.
+	/// </summary>
+	/// <param name="inviteCode">The invite code.</param>
+	/// <param name="targetUserIds">User ids allowed to accept the invite.</param>
+	/// <param name="reason">The audit log reason.</param>
+	/// <exception cref="NotFoundException">Thrown when the invite does not exist.</exception>
+	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
+	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
+	public Task UpdateInviteTargetUsersAsync(string inviteCode, IEnumerable<ulong> targetUserIds, string reason = null)
+		=> this.ApiClient.UpdateInviteTargetUsersAsync(inviteCode, null, targetUserIds, null, reason);
+
+	/// <summary>
+	///     Updates the target users allowed to accept an invite using user objects.
+	/// </summary>
+	/// <param name="inviteCode">The invite code.</param>
+	/// <param name="targetUsers">Users allowed to accept the invite.</param>
+	/// <param name="reason">The audit log reason.</param>
+	/// <exception cref="NotFoundException">Thrown when the invite does not exist.</exception>
+	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
+	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
+	public Task UpdateInviteTargetUsersAsync(string inviteCode, IEnumerable<DiscordUser> targetUsers, string reason = null)
+		=> this.ApiClient.UpdateInviteTargetUsersAsync(inviteCode, null, null, targetUsers, reason);
+
+	/// <summary>
+	///     Gets the invite target users job status.
+	/// </summary>
+	/// <param name="inviteCode">The invite code.</param>
+	/// <returns>The job status.</returns>
+	/// <exception cref="NotFoundException">Thrown when the invite does not exist.</exception>
+	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
+	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
+	public Task<DiscordInviteTargetUsersJobStatus> GetInviteTargetUsersJobStatusAsync(string inviteCode)
+		=> this.ApiClient.GetInviteTargetUsersJobStatusAsync(inviteCode);
+
 	/// <summary>
 	///     Gets a list of user connections.
 	/// </summary>

DisCatSharp/Entities/Channel/DiscordChannel.cs

@@ -1121,15 +1121,25 @@ public Task<IReadOnlyList<DiscordInvite>> GetInvitesAsync() =>
 	/// <param name="targetApplicationId">The target activity ID. Defaults to null.</param>
 	/// <param name="targetUser">The target user id. Defaults to null.</param>
 	/// <param name="reason">The audit log reason.</param>
+	/// <param name="roleIds">Role ids to grant when the invite is accepted.</param>
+	/// <param name="targetUserIds">Allowed target user ids for the invite.</param>
+	/// <param name="targetUsers">Allowed target users for the invite.</param>
+	/// <param name="targetUsersCsv">Optional CSV stream defining allowed users.</param>
 	/// <exception cref="UnauthorizedException">
 	///     Thrown when the client does not have the
 	///     <see cref="Permissions.CreateInstantInvite" /> permission.
 	/// </exception>
 	/// <exception cref="NotFoundException">Thrown when the channel does not exist.</exception>
 	/// <exception cref="BadRequestException">Thrown when an invalid parameter was provided.</exception>
 	/// <exception cref="ServerErrorException">Thrown when Discord is unable to process the request.</exception>
-	public Task<DiscordInvite> CreateInviteAsync(int maxAge = 86400, int maxUses = 0, bool temporary = false, bool unique = false, TargetType? targetType = null, ulong? targetApplicationId = null, ulong? targetUser = null, string reason = null)
-		=> this.Discord.ApiClient.CreateChannelInviteAsync(this.Id, maxAge, maxUses, targetType, targetApplicationId, targetUser, temporary, unique, reason);
+	/// <exception cref="ArgumentException">Thrown when the provided stream is not readable.</exception>
+	public Task<DiscordInvite> CreateInviteAsync(int maxAge = 86400, int maxUses = 0, bool temporary = false, bool unique = false, TargetType? targetType = null, ulong? targetApplicationId = null, ulong? targetUser = null, string reason = null, IEnumerable<ulong>? roleIds = null, IEnumerable<ulong>? targetUserIds = null, IEnumerable<DiscordUser>? targetUsers = null, Stream? targetUsersCsv = null)
+	{
+		if (targetUsersCsv is not null && !targetUsersCsv.CanRead)
+			throw new ArgumentException("The provided stream must be readable.", nameof(targetUsersCsv));
+
+		return this.Discord.ApiClient.CreateChannelInviteAsync(this.Id, maxAge, maxUses, targetType, targetApplicationId, targetUser, temporary, unique, reason, roleIds, targetUserIds, targetUsers, targetUsersCsv);
+	}
 
 	#region Voice Channel
 

DisCatSharp/Entities/Components/V2Components/DiscordCheckboxGroupComponent.cs

@@ -90,7 +90,7 @@ public DiscordCheckboxGroupComponent(IEnumerable<DiscordCheckboxGroupComponentOp
 	///     The submitted values. Present on modal submit interactions.
 	/// </summary>
 	[JsonProperty("values", NullValueHandling = NullValueHandling.Ignore)]
-	public string[]? Values { get; internal set; }
+	public string[]? SelectedValues { get; internal set; }
 
 	/// <summary>
 	///     Assigns a unique id to this component.

DisCatSharp/Entities/Invite/DiscordInviteTargetUsersJobStatus.cs

@@ -0,0 +1,49 @@
+using System;
+
+using DisCatSharp.Enums;
+
+using Newtonsoft.Json;
+
+namespace DisCatSharp.Entities;
+
+/// <summary>
+///     Represents the processing status for invite target users.
+/// </summary>
+public sealed class DiscordInviteTargetUsersJobStatus : ObservableApiObject
+{
+	/// <summary>
+	///     Gets the status of the job.
+	/// </summary>
+	[JsonProperty("status", NullValueHandling = NullValueHandling.Ignore)]
+	public InviteTargetUsersJobStatus Status { get; internal set; }
+
+	/// <summary>
+	///     Gets the total number of users in the job.
+	/// </summary>
+	[JsonProperty("total_users", NullValueHandling = NullValueHandling.Ignore)]
+	public int TotalUsers { get; internal set; }
+
+	/// <summary>
+	///     Gets the processed users count.
+	/// </summary>
+	[JsonProperty("processed_users", NullValueHandling = NullValueHandling.Ignore)]
+	public int ProcessedUsers { get; internal set; }
+
+	/// <summary>
+	///     Gets when the job was created.
+	/// </summary>
+	[JsonProperty("created_at", NullValueHandling = NullValueHandling.Ignore)]
+	public DateTimeOffset CreatedAt { get; internal set; }
+
+	/// <summary>
+	///     Gets when the job completed, if applicable.
+	/// </summary>
+	[JsonProperty("completed_at", NullValueHandling = NullValueHandling.Ignore)]
+	public DateTimeOffset? CompletedAt { get; internal set; }
+
+	/// <summary>
+	///     Gets the error message if the job failed.
+	/// </summary>
+	[JsonProperty("error_message", NullValueHandling = NullValueHandling.Ignore)]
+	public string? ErrorMessage { get; internal set; }
+}

DisCatSharp/Enums/Invite/InviteTargetUsersJobStatus.cs

@@ -0,0 +1,27 @@
+namespace DisCatSharp.Enums;
+
+/// <summary>
+///     Represents the processing status for invite target users jobs.
+/// </summary>
+public enum InviteTargetUsersJobStatus
+{
+	/// <summary>
+	///     The status is unspecified.
+	/// </summary>
+	Unspecified = 0,
+
+	/// <summary>
+	///     The target users job is processing.
+	/// </summary>
+	Processing = 1,
+
+	/// <summary>
+	///     The target users job completed successfully.
+	/// </summary>
+	Completed = 2,
+
+	/// <summary>
+	///     The target users job failed.
+	/// </summary>
+	Failed = 3
+}

DisCatSharp/Net/Abstractions/Rest/RestChannelPayloads.cs

@@ -419,6 +419,12 @@ internal sealed class RestChannelInviteCreatePayload : ObservableApiObject
 	/// </summary>
 	[JsonProperty("unique", NullValueHandling = NullValueHandling.Ignore)]
 	public bool Unique { get; set; }
+
+	/// <summary>
+	///     Gets or sets the role ids to grant when the invite is accepted.
+	/// </summary>
+	[JsonProperty("role_ids", NullValueHandling = NullValueHandling.Ignore)]
+	public IEnumerable<ulong>? RoleIds { get; set; }
 }
 
 /// <summary>