Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add support for ban deletion with seconds precision #2229

Merged
merged 6 commits into from
Aug 30, 2022
Merged

Add support for ban deletion with seconds precision #2229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
263fdff
Add support for ban deletion with seconds precision
MinnDevelopment Aug 29, 2022
7696dee
Update javadocs
MinnDevelopment Aug 30, 2022
d979e03
Update example
MinnDevelopment Aug 30, 2022
f4e03db
Fix deprecation warning
MinnDevelopment Aug 30, 2022
c35cbc7
Fix docs for Member#ban error responses
MinnDevelopment Aug 30, 2022
faa06a2
Make kick non-default
MinnDevelopment Aug 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions src/examples/java/SlashBotExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@

import javax.security.auth.login.LoginException;
import java.util.EnumSet;
import java.util.concurrent.TimeUnit;

import static net.dv8tion.jda.api.interactions.commands.OptionType.*;

Expand Down Expand Up @@ -171,10 +172,10 @@ public void ban(SlashCommandInteractionEvent event, User user, Member member)
OptionMapping::getAsString); // used if getOption("reason") is not null (provided)

// Ban the user and send a success response
event.getGuild().ban(user, delDays, reason)
.reason(reason) // audit-log reason
.flatMap(v -> hook.sendMessage("Banned user " + user.getAsTag()))
.queue();
event.getGuild().ban(user, delDays, TimeUnit.DAYS)
.reason(reason) // audit-log ban reason (sets X-AuditLog-Reason header)
.flatMap(v -> hook.sendMessage("Banned user " + user.getAsTag())) // chain a followup message after the ban is executed
.queue(); // execute the entire call chain
}

public void say(SlashCommandInteractionEvent event, String content)
Expand Down
119 changes: 48 additions & 71 deletions src/main/java/net/dv8tion/jda/api/entities/Guild.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
*/
package net.dv8tion.jda.api.entities;

import net.dv8tion.jda.annotations.DeprecatedSince;
import net.dv8tion.jda.annotations.ForRemoval;
import net.dv8tion.jda.annotations.ReplaceWith;
import net.dv8tion.jda.api.JDA;
import net.dv8tion.jda.api.Permission;
import net.dv8tion.jda.api.Region;
Expand Down Expand Up @@ -57,6 +60,9 @@
import net.dv8tion.jda.internal.utils.Helpers;
import net.dv8tion.jda.internal.utils.concurrent.task.GatewayTask;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.time.Duration;
import java.time.temporal.TemporalAccessor;
import java.util.*;
Expand All @@ -65,10 +71,6 @@
import java.util.function.Consumer;
import java.util.function.Predicate;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
* Represents a Discord {@link net.dv8tion.jda.api.entities.Guild Guild}.
* This should contain all information provided from Discord about a Guild.
Expand Down Expand Up @@ -538,7 +540,6 @@ default ImageProxy getIcon()
* <p>
* <a target="_blank" href="https://discord.com/developers/docs/resources/guild#guild-object-guild-features"><b>List of Features</b></a>
*
*
* @return Never-null, unmodifiable Set containing all of the Guild's features.
*/
@Nonnull
Expand Down Expand Up @@ -1895,7 +1896,7 @@ default RestAction<RichCustomEmoji> retrieveEmoji(@Nonnull CustomEmoji emoji)

/**
* Retrieves an immutable list of the currently banned {@link net.dv8tion.jda.api.entities.User Users}.
* <br>If you wish to ban or unban a user, use either {@link #ban(UserSnowflake, int)} or
* <br>If you wish to ban or unban a user, use either {@link #ban(UserSnowflake, int, TimeUnit)} or
* {@link #unban(UserSnowflake)}.
*
* <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
Expand All @@ -1917,7 +1918,7 @@ default RestAction<RichCustomEmoji> retrieveEmoji(@Nonnull CustomEmoji emoji)

/**
* Retrieves a {@link net.dv8tion.jda.api.entities.Guild.Ban Ban} of the provided {@link UserSnowflake}.
* <br>If you wish to ban or unban a user, use either {@link #ban(UserSnowflake, int)} or {@link #unban(UserSnowflake)}.
* <br>If you wish to ban or unban a user, use either {@link #ban(UserSnowflake, int, TimeUnit)} or {@link #unban(UserSnowflake)}.
*
* <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
* the returned {@link RestAction RestAction} include the following:
Expand Down Expand Up @@ -3182,10 +3183,20 @@ default AuditableRestAction<Integer> prune(int days, @Nonnull Role... roles)
* </ul>
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*
* @deprecated
* Use {@link #kick(UserSnowflake)} and {@link AuditableRestAction#reason(String)} instead.
*/
@Nonnull
@CheckReturnValue
AuditableRestAction<Void> kick(@Nonnull UserSnowflake user, @Nullable String reason);
@Deprecated
@ForRemoval
@ReplaceWith("kick(user).reason(reason)")
@DeprecatedSince("5.0.0")
default AuditableRestAction<Void> kick(@Nonnull UserSnowflake user, @Nullable String reason)
{
return kick(user).reason(reason);
}

/**
* Kicks a {@link net.dv8tion.jda.api.entities.Member Member} from the {@link net.dv8tion.jda.api.entities.Guild Guild}.
Expand Down Expand Up @@ -3219,21 +3230,33 @@ default AuditableRestAction<Integer> prune(int days, @Nonnull Role... roles)
*/
@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> kick(@Nonnull UserSnowflake user)
{
return kick(user, null);
}
AuditableRestAction<Void> kick(@Nonnull UserSnowflake user);

/**
* Bans the user specified by the provided {@link UserSnowflake} and deletes messages sent by the user based on the amount of delDays.
* <br>If you wish to ban a user without deleting any messages, provide delDays with a value of 0.
* Bans the user specified by the provided {@link UserSnowflake} and deletes messages sent by the user based on the {@code deletionTimeframe}.
* <br>If you wish to ban a user without deleting any messages, provide {@code deletionTimeframe} with a value of 0.
* To set a ban reason, use {@link AuditableRestAction#reason(String)}.
*
* <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserReference)}.
*
* <p><b>Note:</b> {@link net.dv8tion.jda.api.entities.Guild#getMembers()} will still contain the {@link net.dv8tion.jda.api.entities.User User's}
* {@link net.dv8tion.jda.api.entities.Member Member} object (if the User was in the Guild)
* until Discord sends the {@link net.dv8tion.jda.api.events.guild.member.GuildMemberRemoveEvent GuildMemberRemoveEvent}.
*
* <p><b>Examples</b><br>
* Banning a user without deleting any messages:
* <pre>{@code
* guild.ban(user, 0, TimeUnit.SECONDS)
* .reason("Banned for rude behavior")
* .queue();
* }</pre>
* Banning a user and deleting messages from the past hour:
* <pre>{@code
* guild.ban(user, 1, TimeUnit.HOURS)
* .reason("Banned for spamming")
* .queue();
* }</pre>
*
* <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
* the returned {@link RestAction RestAction} include the following:
* <ul>
Expand All @@ -3247,10 +3270,10 @@ default AuditableRestAction<Void> kick(@Nonnull UserSnowflake user)
* @param user
* The {@link UserSnowflake} for the user to ban.
* This can be a member or user instance or {@link User#fromId(long)}.
* @param delDays
* The history of messages, in days, that will be deleted.
* @param reason
* The reason for this action or {@code null} if there is no specified reason
* @param deletionTimeframe
* The timeframe for the history of messages that will be deleted. (seconds precision)
* @param unit
* Timeframe unit as a {@link TimeUnit} (for example {@code ban(user, 7, TimeUnit.DAYS)}).
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#BAN_MEMBERS} permission.
Expand All @@ -3259,64 +3282,18 @@ default AuditableRestAction<Void> kick(@Nonnull UserSnowflake user)
* <br>See {@link Member#canInteract(Member)}
* @throws java.lang.IllegalArgumentException
* <ul>
* <li>If the provided amount of days (delDays) is less than 0.</li>
* <li>If the provided amount of days (delDays) is bigger than 7.</li>
* <li>If the provided reason is longer than 512 characters.</li>
* <li>If the provided user is {@code null}</li>
* <li>If the provided deletionTimeframe is negative.</li>
* <li>If the provided deletionTimeframe is longer than 7 days.</li>
* <li>If the provided user or time unit is {@code null}</li>
* </ul>
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*/
@Nonnull
@CheckReturnValue
AuditableRestAction<Void> ban(@Nonnull UserSnowflake user, int delDays, @Nullable String reason);

/**
* Bans the {@link UserSnowflake} and deletes messages sent by the user based on the amount of delDays.
* <br>If you wish to ban a member without deleting any messages, provide delDays with a value of 0.
*
* <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserReference)}.
*
* <p><b>Note:</b> {@link net.dv8tion.jda.api.entities.Guild#getMembers()} will still contain the
* {@link net.dv8tion.jda.api.entities.Member Member} until Discord sends the
* {@link net.dv8tion.jda.api.events.guild.member.GuildMemberRemoveEvent GuildMemberRemoveEvent}.
*
* <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
* the returned {@link RestAction RestAction} include the following:
* <ul>
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The target Member cannot be banned due to a permission discrepancy</li>
*
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
* <br>The specified User does not exit</li>
* </ul>
*
* @param user
* The {@link UserSnowflake} for the user to ban.
* This can be a member or user instance or {@link User#fromId(long)}.
* @param delDays
* The history of messages, in days, that will be deleted.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#BAN_MEMBERS} permission.
* @throws net.dv8tion.jda.api.exceptions.HierarchyException
* If the logged in account cannot ban the other user due to permission hierarchy position.
* <br>See {@link Member#canInteract(Member)}
* @throws java.lang.IllegalArgumentException
* <ul>
* <li>If the provided amount of days (delDays) is less than 0.</li>
* <li>If the provided amount of days (delDays) is bigger than 7.</li>
* <li>If the provided user is {@code null}</li>
* </ul>
* @return {@link AuditableRestAction}
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
* @see AuditableRestAction#reason(String)
*/
@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> ban(@Nonnull UserSnowflake user, int delDays)
{
return ban(user, delDays, null);
}
AuditableRestAction<Void> ban(@Nonnull UserSnowflake user, int deletionTimeframe, @Nonnull TimeUnit unit);

/**
* Unbans the specified {@link UserSnowflake} from this Guild.
Expand All @@ -3328,7 +3305,7 @@ default AuditableRestAction<Void> ban(@Nonnull UserSnowflake user, int delDays)
* <br>The target Member cannot be unbanned due to a permission discrepancy</li>
*
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
* <br>The specified User is invalid</li>
* <br>The specified User does not exist</li>
* </ul>
*
* @param user
Expand Down
86 changes: 25 additions & 61 deletions src/main/java/net/dv8tion/jda/api/entities/Member.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@

package net.dv8tion.jda.api.entities;

import net.dv8tion.jda.annotations.DeprecatedSince;
import net.dv8tion.jda.annotations.ForRemoval;
import net.dv8tion.jda.annotations.Incubating;
import net.dv8tion.jda.annotations.ReplaceWith;
import net.dv8tion.jda.api.JDA;
import net.dv8tion.jda.api.OnlineStatus;
import net.dv8tion.jda.api.entities.channel.unions.DefaultGuildChannelUnion;
Expand Down Expand Up @@ -439,7 +442,8 @@ default ImageProxy getEffectiveAvatar()

/**
* Bans this Member and deletes messages sent by the user based on the amount of delDays.
* <br>If you wish to ban a member without deleting any messages, provide delDays with a value of 0.
* <br>If you wish to ban a user without deleting any messages, provide {@code deletionTimeframe} with a value of 0.
* To set a ban reason, use {@link AuditableRestAction#reason(String)}.
*
* <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserSnowflake)}.
*
Expand All @@ -453,59 +457,14 @@ default ImageProxy getEffectiveAvatar()
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The target Member cannot be banned due to a permission discrepancy</li>
*
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MEMBER UNKNOWN_MEMBER}
* <br>The specified Member was removed from the Guild before finishing the task</li>
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
* <br>The user no longer exists</li>
* </ul>
*
* @param delDays
* The history of messages, in days, that will be deleted.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#BAN_MEMBERS} permission.
* @throws net.dv8tion.jda.api.exceptions.HierarchyException
* If the logged in account cannot ban the other user due to permission hierarchy position.
* <br>See {@link Member#canInteract(Member)}
* @throws java.lang.IllegalArgumentException
* <ul>
* <li>If the provided amount of days (delDays) is less than 0.</li>
* <li>If the provided amount of days (delDays) is bigger than 7.</li>
* </ul>
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*
* @since 4.0.0
*/
@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> ban(int delDays)
{
return getGuild().ban(this, delDays);
}

/**
* Bans this Member and deletes messages sent by the user based on the amount of delDays.
* <br>If you wish to ban a member without deleting any messages, provide delDays with a value of 0.
*
* <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserSnowflake)}.
*
* <p><b>Note:</b> {@link net.dv8tion.jda.api.entities.Guild#getMembers()} will still contain the
* {@link net.dv8tion.jda.api.entities.Member Member} until Discord sends the
* {@link net.dv8tion.jda.api.events.guild.member.GuildMemberRemoveEvent GuildMemberRemoveEvent}.
*
* <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
* the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
* <ul>
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The target Member cannot be banned due to a permission discrepancy</li>
*
* <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MEMBER UNKNOWN_MEMBER}
* <br>The specified Member was removed from the Guild before finishing the task</li>
* </ul>
*
* @param delDays
* The history of messages, in days, that will be deleted.
* @param reason
* The reason for this action or {@code null} if there is no specified reason
* @param deletionTimeframe
* The timeframe for the history of messages that will be deleted. (seconds precision)
* @param unit
* Timeframe unit as a {@link TimeUnit} (for example {@code member.ban(7, TimeUnit.DAYS)}).
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#BAN_MEMBERS} permission.
Expand All @@ -514,21 +473,21 @@ default AuditableRestAction<Void> ban(int delDays)
* <br>See {@link Member#canInteract(Member)}
* @throws java.lang.IllegalArgumentException
* <ul>
* <li>If the provided amount of days (delDays) is less than 0.</li>
* <li>If the provided amount of days (delDays) is bigger than 7.</li>
* <li>If the provided reason is longer than 512 characters.</li>
* <li>If the provided deletionTimeframe is negative.</li>
* <li>If the provided deletionTimeframe is longer than 7 days.</li>
* <li>If the provided time unit is {@code null}</li>
* </ul>
*
* @return {@link AuditableRestAction}
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*
* @since 4.0.0
* @see Guild#ban(UserSnowflake, int, TimeUnit)
* @see AuditableRestAction#reason(String)
*/
@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> ban(int delDays, @Nullable String reason)
default AuditableRestAction<Void> ban(int deletionTimeframe, @Nonnull TimeUnit unit)
{
return getGuild().ban(this, delDays, reason);
return getGuild().ban(this, deletionTimeframe, unit);
}

/**
Expand Down Expand Up @@ -595,10 +554,15 @@ default AuditableRestAction<Void> kick()
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
* Kicks the provided Member from the current Guild
*
* @since 4.0.0
* @deprecated
* Use {@link #kick()} and {@link AuditableRestAction#reason(String)} instead
*/
@Nonnull
@CheckReturnValue
@Deprecated
@ForRemoval
@ReplaceWith("kick().reason(reason)")
@DeprecatedSince("5.0.0")
default AuditableRestAction<Void> kick(@Nullable String reason)
{
return getGuild().kick(this, reason);
Expand Down
Loading