Merge remote-tracking branch 'origin/master' into patch/publish-plugin

# Conflicts:
#	build.gradle.kts

.github/CONTRIBUTING.md

@@ -1,33 +1,16 @@
-
 ## Making Changes
 
-Depending on your changes there are certain rules you have to follow if you expect
-your Pull Request to be merged.
-
-**Note**: It is recommended to create a new remote branch for each Pull Request. 
-Based on the current `master` changes!
-
-1. Adding a new Method or Class
-    - If your addition is not internal (e.g. an impl class or private method) you have to write documentation.
-        - For that please follow the [JavaDoc template](https://jda.wiki/contributing/structure-guide/#javadoc)
-    - Keep your code consistent! [example](https://jda.wiki/contributing/contributing/#making-changes)
-        - Follow the guides provided at [JDA Structure Guide](https://jda.wiki/contributing/structure-guide/)
-        - Compare your code style to the one used all over JDA and ensure you
-          do not break the consistency (if you find issues in the JDA style you can include and update it)
-    - Do not remove existing functionality, use deprecation instead (for reference [deprecation policy](https://github.com/discord-jda/JDA?tab=readme-ov-file#versioning-and-deprecation-policy))
+Depending on your changes there are certain rules you have to follow if you expect your Pull Request (PR) to be merged.
 
-2. Making a Commit
-    - While having multiple commits can help the reader understand your changes, it might sometimes be
-      better to include more changes in a single commit.
-    - When you commit your changes write a proper commit caption which explains what you have done
+1. Check for existing pull requests that might already implement your changes.  
+    You can review those pull requests with your suggestions for improvements.
+1. Reference documentation or issues that are relevant to your changes.  
+    For instance, if you're implementing a new Discord feature, include a link to the [api docs](https://github.com/discord/discord-api-docs) pull request that documents the feature.
+1. If you implement a new feature, include some examples on how you intend it to be used in your PR description.
+1. Write documentation for all public API methods and types.
+1. Follow the JDA coding style, even if unconventional, we want to keep it consistent to maintain readability.
+1. Try to limit your PR to one logical change or closely related changes.  
+    For instance, do not refactor other code that is irrelevant to your changes. If you want to refactor something, make a dedicated PR.
 
-3. Updating your Fork
-    - Before you start committing make sure your fork is updated.
-      (See [Syncing a Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
-      or [Keeping a Fork Updated](https://thoughtbot.com/blog/keeping-a-github-fork-updated))
-
-4. Only open Pull Requests to master
-    - Look at the [Repository Structure](https://jda.wiki/contributing/repository-structure/) for further details
-
-For more information please consult the [Contributing](https://jda.wiki/contributing/contributing/)
-section of our wiki.
+> [!TIP]
+> Before starting to implement your changes, you can post in our [lib-dev](https://discord.gg/qcy8K58zWb) channel on our Discord Server. Getting early feedback will help you and the reviewers save a lot of time.

build.gradle.kts

@@ -28,7 +28,7 @@ plugins {
     `maven-publish`
 
     id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
-    id("com.github.johnrengelman.shadow") version "7.1.2"
+    id("com.github.johnrengelman.shadow") version "8.1.1"
 }
 
 
@@ -107,33 +107,32 @@ dependencies {
     /* ABI dependencies */
 
     //Code safety
-    compileOnly("com.google.code.findbugs:jsr305:3.0.2")
-    compileOnly("org.jetbrains:annotations:23.0.0")
+    compileOnly(libs.findbugs)
+    compileOnly(libs.jetbrains.annotations)
 
     //Logger
-    api("org.slf4j:slf4j-api:1.7.36")
+    api(libs.slf4j)
 
     //Web Connection Support
-    api("com.neovisionaries:nv-websocket-client:2.14")
-    api("com.squareup.okhttp3:okhttp:4.12.0")
+    api(libs.websocket.client)
+    api(libs.okhttp)
 
     //Opus library support
-    api("club.minnced:opus-java:1.1.1")
+    api(libs.opus)
 
     //Collections Utility
-    api("org.apache.commons:commons-collections4:4.4")
+    api(libs.commons.collections)
 
     //we use this only together with opus-java
     // if that dependency is excluded it also doesn't need jna anymore
     // since jna is a transitive runtime dependency of opus-java we don't include it explicitly as dependency
-    compileOnly("net.java.dev.jna:jna:4.4.0")
+    compileOnly(libs.jna)
 
     /* Internal dependencies */
 
     //General Utility
-    implementation("net.sf.trove4j:trove4j:3.0.3")
-    implementation("com.fasterxml.jackson.core:jackson-core:2.16.0")
-    implementation("com.fasterxml.jackson.core:jackson-databind:2.16.0")
+    implementation(libs.trove4j)
+    implementation(libs.bundles.jackson)
 
     //Sets the dependencies for the examples
     configurations["examplesImplementation"].withDependencies {
@@ -142,10 +141,11 @@ dependencies {
         addAll(configurations["compileOnly"].allDependencies)
     }
 
-    testImplementation("org.junit.jupiter:junit-jupiter:5.10.1")
-    testImplementation("org.reflections:reflections:0.10.2")
-    testImplementation("org.mockito:mockito-core:5.8.0")
-    testImplementation("org.assertj:assertj-core:3.25.3")
+    testImplementation(libs.junit)
+    testImplementation(libs.reflections)
+    testImplementation(libs.mockito)
+    testImplementation(libs.assertj)
+    testImplementation(libs.commons.lang3)
 }
 
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

settings.gradle.kts

@@ -1 +1,27 @@
 rootProject.name = "JDA"
+
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            version("jackson", "2.16.0")
+            library("jackson-core",     "com.fasterxml.jackson.core", "jackson-core").versionRef("jackson")
+            library("jackson-databind", "com.fasterxml.jackson.core", "jackson-databind").versionRef("jackson")
+            bundle("jackson", listOf("jackson-core", "jackson-databind"))
+
+            library("opus",                  "club.minnced",             "opus-java"           ).version("1.1.1")
+            library("findbugs",              "com.google.code.findbugs", "jsr305"              ).version("3.0.2")
+            library("websocket-client",      "com.neovisionaries",       "nv-websocket-client" ).version("2.14")
+            library("okhttp",                "com.squareup.okhttp3",     "okhttp"              ).version("4.12.0")
+            library("jna",                   "net.java.dev.jna",         "jna"                 ).version("5.14.0")
+            library("trove4j",               "net.sf.trove4j",           "core"                ).version("3.1.0")
+            library("commons-collections",   "org.apache.commons",       "commons-collections4").version("4.4")
+            library("commons-lang3",         "org.apache.commons",       "commons-lang3"       ).version("3.14.0")
+            library("assertj",               "org.assertj",              "assertj-core"        ).version("3.25.3")
+            library("jetbrains-annotations", "org.jetbrains",            "annotations"         ).version("24.1.0")
+            library("junit",                 "org.junit.jupiter",        "junit-jupiter"       ).version("5.10.2")
+            library("mockito",               "org.mockito",              "mockito-core"        ).version("5.11.0")
+            library("reflections",           "org.reflections",          "reflections"         ).version("0.10.2")
+            library("slf4j",                 "org.slf4j",                "slf4j-api"           ).version("1.7.36")
+        }
+    }
+}

src/main/java/net/dv8tion/jda/api/Permission.java

@@ -15,8 +15,6 @@
  */
 package net.dv8tion.jda.api;
 
-import net.dv8tion.jda.annotations.ForRemoval;
-import net.dv8tion.jda.annotations.ReplaceWith;
 import net.dv8tion.jda.internal.utils.Checks;
 
 import javax.annotation.Nonnull;
@@ -33,19 +31,17 @@ public enum Permission
     // General Server / Channel Permissions
     MANAGE_CHANNEL(                      4, true,  true,  "Manage Channels"),
     MANAGE_SERVER(                       5, true,  false, "Manage Server"),
-    VIEW_AUDIT_LOGS(                     7, true,  false, "View Audit Logs"),
-    VIEW_CHANNEL(                       10, true,  true,  "View Channel(s)"),
+    VIEW_AUDIT_LOGS(                     7, true,  false, "View Audit Log"),
+    VIEW_CHANNEL(                       10, true,  true,  "View Channels"),
     VIEW_GUILD_INSIGHTS(                19, true,  false, "View Server Insights"),
     MANAGE_ROLES(                       28, true,  false, "Manage Roles"),
     MANAGE_PERMISSIONS(                 28, false, true,  "Manage Permissions"),
     MANAGE_WEBHOOKS(                    29, true,  true,  "Manage Webhooks"),
-    @Deprecated
-    @ForRemoval(deadline = "5.0.0")
-    @ReplaceWith("MANAGE_GUILD_EXPRESSIONS")
-    MANAGE_EMOJIS_AND_STICKERS(         30, true,  false, "Manage Emojis and Stickers"),
-    MANAGE_GUILD_EXPRESSIONS(           30, true,  false, "Manage Emojis, Stickers, and Soundboards"),
+    MANAGE_GUILD_EXPRESSIONS(           30, true,  false, "Manage Expressions"),
     MANAGE_EVENTS(                      33, true,  true,  "Manage Events"),
     VIEW_CREATOR_MONETIZATION_ANALYTICS(41, true,  false, "View Creator Analytics"),
+    CREATE_GUILD_EXPRESSIONS(           43, true,  false, "Create Expressions"),
+    CREATE_SCHEDULED_EVENTS(            44, true,  false, "Create Events"),
 
     // Membership Permissions
     CREATE_INSTANT_INVITE(0, true, true,  "Create Instant Invite"),
@@ -68,6 +64,7 @@ public enum Permission
     USE_APPLICATION_COMMANDS(    31, true, true, "Use Application Commands"),
     MESSAGE_EXT_STICKER(         37, true, true, "Use External Stickers"),
     MESSAGE_ATTACH_VOICE_MESSAGE(46, true, true, "Send Voice Messages"),
+    MESSAGE_SEND_POLLS(          49, true, true, "Create Polls"),
 
     // Thread Permissions
     MANAGE_THREADS(          34, true, true, "Manage Threads"),

src/main/java/net/dv8tion/jda/api/entities/Message.java

@@ -31,6 +31,7 @@
 import net.dv8tion.jda.api.entities.emoji.CustomEmoji;
 import net.dv8tion.jda.api.entities.emoji.Emoji;
 import net.dv8tion.jda.api.entities.emoji.RichCustomEmoji;
+import net.dv8tion.jda.api.entities.messages.MessagePoll;
 import net.dv8tion.jda.api.entities.sticker.GuildSticker;
 import net.dv8tion.jda.api.entities.sticker.Sticker;
 import net.dv8tion.jda.api.entities.sticker.StickerItem;
@@ -48,17 +49,20 @@
 import net.dv8tion.jda.api.requests.restaction.MessageCreateAction;
 import net.dv8tion.jda.api.requests.restaction.MessageEditAction;
 import net.dv8tion.jda.api.requests.restaction.ThreadChannelAction;
+import net.dv8tion.jda.api.requests.restaction.pagination.PollVotersPaginationAction;
 import net.dv8tion.jda.api.requests.restaction.pagination.ReactionPaginationAction;
 import net.dv8tion.jda.api.utils.AttachedFile;
 import net.dv8tion.jda.api.utils.AttachmentProxy;
 import net.dv8tion.jda.api.utils.FileUpload;
 import net.dv8tion.jda.api.utils.data.DataObject;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 import net.dv8tion.jda.api.utils.messages.MessageEditData;
+import net.dv8tion.jda.api.utils.messages.MessagePollData;
 import net.dv8tion.jda.api.utils.messages.MessageRequest;
 import net.dv8tion.jda.internal.JDAImpl;
 import net.dv8tion.jda.internal.entities.ReceivedMessage;
 import net.dv8tion.jda.internal.requests.FunctionalCallback;
+import net.dv8tion.jda.internal.requests.restaction.pagination.PollVotersPaginationActionImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 import net.dv8tion.jda.internal.utils.Helpers;
 import net.dv8tion.jda.internal.utils.IOUtil;
@@ -681,6 +685,43 @@ default String getGuildId()
     @Nonnull
     List<LayoutComponent> getComponents();
 
+    /**
+     * The {@link MessagePoll} attached to this message.
+     *
+     * @return Possibly-null poll instance for this message
+     *
+     * @see    #endPoll()
+     */
+    @Nullable
+    MessagePoll getPoll();
+
+    /**
+     * End the poll attached to this message.
+     *
+     * @throws IllegalStateException
+     *         If this poll was not sent by the currently logged in account or no poll was attached to this message
+     *
+     * @return {@link AuditableRestAction} - Type: {@link Message}
+     */
+    @Nonnull
+    @CheckReturnValue
+    AuditableRestAction<Message> endPoll();
+
+    /**
+     * Paginate the users who voted for a poll answer.
+     *
+     * @param  answerId
+     *         The id of the poll answer, usually the ordinal position of the answer (first is 1)
+     *
+     * @return {@link PollVotersPaginationAction}
+     */
+    @Nonnull
+    @CheckReturnValue
+    default PollVotersPaginationAction retrievePollVoters(long answerId)
+    {
+        return new PollVotersPaginationActionImpl(getJDA(), getChannelId(), getId(), answerId);
+    }
+
     /**
      * Rows of interactive components such as {@link Button Buttons}.
      * <br>You can use {@link MessageRequest#setComponents(LayoutComponent...)} to update these.
@@ -1359,6 +1400,48 @@ default MessageCreateAction reply(@Nonnull MessageCreateData msg)
         return getChannel().sendMessage(msg).setMessageReference(this);
     }
 
+    /**
+     * Shortcut for {@code getChannel().sendMessagePoll(data).setMessageReference(this)}.
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} include:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
+     *     <br>if this channel was deleted</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#CANNOT_SEND_TO_USER CANNOT_SEND_TO_USER}
+     *     <br>If this is a {@link PrivateChannel} and the currently logged in account
+     *         does not share any Guilds with the recipient User</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MESSAGE_BLOCKED_BY_AUTOMOD MESSAGE_BLOCKED_BY_AUTOMOD}
+     *     <br>If this message was blocked by an {@link net.dv8tion.jda.api.entities.automod.AutoModRule AutoModRule}</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER}
+     *     <br>If this message was blocked by the harmful link filter</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#POLL_INVALID_CHANNEL_TYPE POLL_INVALID_CHANNEL_TYPE}
+     *     <br>This channel does not allow polls</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#POLL_WITH_UNUSABLE_EMOJI POLL_WITH_UNUSABLE_EMOJI}
+     *     <br>This poll uses an external emoji that the bot is not allowed to use</li>
+     * </ul>
+     *
+     * @param  poll
+     *         The poll to send
+     *
+     * @throws InsufficientPermissionException
+     *         If {@link MessageChannel#sendMessage(MessageCreateData)} throws
+     * @throws IllegalArgumentException
+     *         If {@link MessageChannel#sendMessage(MessageCreateData)} throws
+     *
+     * @return {@link MessageCreateAction}
+     */
+    @Nonnull
+    @CheckReturnValue
+    default MessageCreateAction replyPoll(@Nonnull MessagePollData poll)
+    {
+        return getChannel().sendMessagePoll(poll).setMessageReference(this);
+    }
+
     /**
      * Shortcut for {@code getChannel().sendMessageEmbeds(embed, other).setMessageReference(this)}.
      *

src/main/java/net/dv8tion/jda/api/entities/WebhookClient.java

@@ -32,6 +32,8 @@
 import net.dv8tion.jda.api.utils.MiscUtil;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 import net.dv8tion.jda.api.utils.messages.MessageEditData;
+import net.dv8tion.jda.api.utils.messages.MessagePollBuilder;
+import net.dv8tion.jda.api.utils.messages.MessagePollData;
 import net.dv8tion.jda.internal.requests.IncomingWebhookClientImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 
@@ -128,6 +130,43 @@ public interface WebhookClient<T> extends ISnowflake
     @CheckReturnValue
     WebhookMessageCreateAction<T> sendMessage(@Nonnull MessageCreateData message);
 
+    /**
+     * Send a message poll to this webhook.
+     *
+     * <p>If this is an {@link InteractionHook InteractionHook} this method will be delayed until the interaction is acknowledged.
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} include:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_WEBHOOK UNKNOWN_WEBHOOK}
+     *     <br>The webhook is no longer available, either it was deleted or in case of interactions it expired.</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MESSAGE_BLOCKED_BY_AUTOMOD MESSAGE_BLOCKED_BY_AUTOMOD}
+     *     <br>If this message was blocked by an {@link net.dv8tion.jda.api.entities.automod.AutoModRule AutoModRule}</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER}
+     *     <br>If this message was blocked by the harmful link filter</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#POLL_INVALID_CHANNEL_TYPE POLL_INVALID_CHANNEL_TYPE}
+     *     <br>This channel does not allow polls</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#POLL_WITH_UNUSABLE_EMOJI POLL_WITH_UNUSABLE_EMOJI}
+     *     <br>This poll uses an external emoji that the bot is not allowed to use</li>
+     * </ul>
+     *
+     * @param  poll
+     *         The {@link MessagePollData} to send
+     *
+     * @throws IllegalArgumentException
+     *         If null is provided
+     *
+     * @return {@link net.dv8tion.jda.api.requests.restaction.WebhookMessageCreateAction}
+     *
+     * @see    MessagePollBuilder
+     */
+    @Nonnull
+    @CheckReturnValue
+    WebhookMessageCreateAction<T> sendMessagePoll(@Nonnull MessagePollData poll);
+
     /**
      * Send a message to this webhook.
      *