Necessary additions for role subscriptions (#2375)

* Add new role tags
* Add new message type
* Add new error responses
* Add new invite target type
* Add support for connection metadata configuration

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

@@ -828,6 +828,36 @@ default RestAction<Void> deleteCommandById(long commandId)
         return deleteCommandById(Long.toUnsignedString(commandId));
     }
 
+    /**
+     * Retrieves the currently configured {@link RoleConnectionMetadata} records for this application.
+     *
+     * @return {@link RestAction} - Type: {@link List} of {@link RoleConnectionMetadata}
+     *
+     * @see <a href="https://discord.com/developers/docs/tutorials/configuring-app-metadata-for-linked-roles" target="_blank">Configuring App Metadata for Linked Roles</a>
+     */
+    @Nonnull
+    @CheckReturnValue
+    RestAction<List<RoleConnectionMetadata>> retrieveRoleConnectionMetadata();
+
+    /**
+     * Updates the currently configured {@link RoleConnectionMetadata} records for this application.
+     *
+     * <p>Returns the updated connection metadata records on success.
+     *
+     * @param  records
+     *         The new records to set
+     *
+     * @throws IllegalArgumentException
+     *         If null is provided or more than {@value RoleConnectionMetadata#MAX_RECORDS} records are configured.
+     *
+     * @return {@link RestAction} - Type: {@link List} of {@link RoleConnectionMetadata}
+     *
+     * @see <a href="https://discord.com/developers/docs/tutorials/configuring-app-metadata-for-linked-roles" target="_blank">Configuring App Metadata for Linked Roles</a>
+     */
+    @Nonnull
+    @CheckReturnValue
+    RestAction<List<RoleConnectionMetadata>> updateRoleConnectionMetadata(@Nonnull Collection<? extends RoleConnectionMetadata> records);
+
     /**
      * Constructs a new {@link Guild Guild} with the specified name
      * <br>Use the returned {@link GuildAction GuildAction} to provide

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

@@ -723,6 +723,12 @@ enum TargetType
          */
         EMBEDDED_APPLICATION(2),
 
+        /**
+         * The invite points to a role subscription listing in a guild.
+         * <br>These cannot be created by bots.
+         */
+        ROLE_SUBSCRIPTIONS_PURCHASE(3),
+
         /**
          * Unknown Discord invite target type. Should never happen and would only possibly happen if Discord implemented a new
          * target type and JDA had yet to implement support for it.

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

@@ -150,6 +150,14 @@ public enum MessageType
      */
     AUTO_MODERATION_ACTION(24, true, true),
 
+    /**
+     * Sent when someone purchases a role subscription.
+     *
+     * @see Role.RoleTags#isAvailableForPurchase()
+     * @see Role.RoleTags#hasSubscriptionListing()
+     */
+    ROLE_SUBSCRIPTION_PURCHASE(25, true, true),
+
     /**
      * Unknown MessageType.
      */

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

@@ -373,5 +373,67 @@ default String getIntegrationId()
         {
             return isIntegration() ? Long.toUnsignedString(getIntegrationIdLong()) : null;
         }
+
+        /**
+         * Whether this role can be acquired through a premium subscription purchase.
+         * A role would also need {@link #isAvailableForPurchase()} to also be true for a user to actually be
+         * able to purchase the role. 
+         *
+         * @return True, if this is a subscription role
+         *
+         * @see    #getSubscriptionIdLong()
+         * @see    #isAvailableForPurchase()
+         */
+        default boolean hasSubscriptionListing()
+        {
+            return getSubscriptionIdLong() != 0;
+        }
+
+        /**
+         * The subscription listing id for this role. If a role has a subscription id then it is a premium role that 
+         * can be acquired by users via purchase.
+         *
+         * @return The listing id, or 0 if this role is not for a subscription listing
+         *
+         * @see    #isAvailableForPurchase()
+         */
+        long getSubscriptionIdLong();
+
+        /**
+         * The subscription listing id for this role. If a role has a subscription id then it is a premium role that 
+         * can be acquired by users via purchase.
+         *
+         * @return The listing id, or null if this role is not for a subscription listing
+         *
+         * @see    #isAvailableForPurchase()
+         */
+        @Nullable
+        default String getSubscriptionId()
+        {
+            return hasSubscriptionListing() ? Long.toUnsignedString(getSubscriptionIdLong()) : null;
+        }
+
+        /**
+         * Whether this role has been published for user purchasing. Only {@link #hasSubscriptionListing() premium roles} 
+         * can be purchased. However, a premium role must be published before it can be purchased. 
+         * Additionally, a premium role can be unpublished after it has been published. Doing so will make it 
+         * no longer available for purchase but will not remove the role from users who have already purchased it.
+         *
+         * @return True, if this role is purchasable
+         *
+         * @see    #hasSubscriptionListing()
+         */
+        boolean isAvailableForPurchase();
+
+        /**
+         * Whether this role is acquired through a user connection.
+         * <br>Such as external services like twitter or reddit.
+         * This also includes custom third-party applications, such as those managed by bots via {@link RoleConnectionMetadata}.
+         *
+         * @return True, if this role is acquired through a user connection
+         *
+         * @see    <a href="https://discord.com/developers/docs/tutorials/configuring-app-metadata-for-linked-roles" target="_blank">Configuring App Metadata for Linked Roles</a>
+         */
+        boolean isLinkedRole();
     }
 }