Skip to content

Commit

Permalink
Add support for ban deletion with seconds precision (#2229)
Browse files Browse the repository at this point in the history 
And remove reason parameter in favor of reason setter
  • Loading branch information
@MinnDevelopment
MinnDevelopment committed Aug 30, 2022
1 parent 31b1bfb commit a2d3267
Show file tree
Hide file tree
Showing 5 changed files with 97 additions and 160 deletions.
9 changes: 5 additions & 4 deletions src/examples/java/SlashBotExample.java
View file
Expand Up @@ -33,6 +33,7 @@
import net.dv8tion.jda.api.requests.restaction.CommandListUpdateAction;

import java.util.EnumSet;
import java.util.concurrent.TimeUnit;

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

Expand Down Expand Up @@ -170,10 +171,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
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
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

0 comments on commit a2d3267

Please sign in to comment.