Add missing features relating to premium app subscriptions (#2667)

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

@@ -1899,6 +1899,117 @@ default List<RichCustomEmoji> getEmojisByName(@Nonnull String name, boolean igno
     @CheckReturnValue
     EntitlementPaginationAction retrieveEntitlements();
 
+    /**
+     * Retrieves an {@link Entitlement} by its id.
+     *
+     * @param  entitlementId
+     *         The id of the entitlement to retrieve
+     *
+     * @throws IllegalArgumentException
+     *         If the provided id is not a valid snowflake
+     *
+     * @return {@link RestAction} - Type: {@link Entitlement}
+     *         <br>The entitlement with the provided id
+     */
+    @Nonnull
+    @CheckReturnValue
+    default RestAction<Entitlement> retrieveEntitlementById(@Nonnull String entitlementId)
+    {
+        return retrieveEntitlementById(MiscUtil.parseSnowflake(entitlementId));
+    }
+
+    /**
+     * Retrieves an {@link Entitlement} by its id.
+     *
+     * @param  entitlementId
+     *         The id of the entitlement to retrieve
+     *
+     * @return {@link RestAction} - Type: {@link Entitlement}
+     *         <br>The entitlement with the provided id
+     */
+    @Nonnull
+    @CheckReturnValue
+    RestAction<Entitlement> retrieveEntitlementById(long entitlementId);
+
+    /**
+     * Constructs a new {@link Entitlement Entitlement} with the skuId and the type.
+     * <br>Use the returned {@link TestEntitlementCreateAction TestEntitlementCreateAction} to provide more details.
+     *
+     * @param  skuId
+     *         The id of the SKU the entitlement is for
+     *
+     * @param ownerId
+     *        The id of the owner of the entitlement
+     *
+     * @param ownerType
+     *        The type of the owner of the entitlement
+     *
+     * @throws IllegalArgumentException
+     *         If the provided skuId or ownerId is not a valid snowflake
+     *
+     * @return {@link TestEntitlementCreateAction TestEntitlementCreateAction}
+     *         <br>Allows for setting various details for the resulting Entitlement
+     */
+    @Nonnull
+    @CheckReturnValue
+    default TestEntitlementCreateAction createTestEntitlement(@Nonnull String skuId, @Nonnull String ownerId, @Nonnull TestEntitlementCreateAction.OwnerType ownerType)
+    {
+        return createTestEntitlement(MiscUtil.parseSnowflake(skuId), MiscUtil.parseSnowflake(ownerId), ownerType);
+    }
+
+    /**
+     * Constructs a new {@link Entitlement Entitlement} with the skuId and the type.
+     * <br>Use the returned {@link TestEntitlementCreateAction TestEntitlementCreateAction} to provide more details.
+     *
+     * @param  skuId
+     *         The id of the SKU the entitlement is for
+     *
+     * @param ownerId
+     *        The id of the owner of the entitlement
+     *
+     * @param ownerType
+     *        The type of the owner of the entitlement
+     *
+     * @throws IllegalArgumentException
+     *         If the provided ownerType is null
+     *
+     * @return {@link TestEntitlementCreateAction TestEntitlementCreateAction}
+     *         <br>Allows for setting various details for the resulting Entitlement
+     */
+    @Nonnull
+    @CheckReturnValue
+    TestEntitlementCreateAction createTestEntitlement(long skuId, long ownerId, @Nonnull TestEntitlementCreateAction.OwnerType ownerType);
+
+    /**
+     * Deletes a test entitlement by its id.
+     *
+     * @param  entitlementId
+     *         The id of the entitlement to delete
+     *
+     * @throws IllegalArgumentException
+     *         If the provided id is not a valid snowflake
+     *
+     * @return {@link RestAction} - Type: Void
+     */
+    @Nonnull
+    @CheckReturnValue
+    default RestAction<Void> deleteTestEntitlement(@Nonnull String entitlementId)
+    {
+        return deleteTestEntitlement(MiscUtil.parseSnowflake(entitlementId));
+    }
+
+    /**
+     * Deletes a test entitlement by its id.
+     *
+     * @param  entitlementId
+     *         The id of the entitlement to delete
+     *
+     * @return {@link RestAction} - Type: Void
+     */
+    @Nonnull
+    @CheckReturnValue
+    RestAction<Void> deleteTestEntitlement(long entitlementId);
+
     /**
      * Configures the required scopes applied to the {@link #getInviteUrl(Permission...)} and similar methods.
      * <br>To use slash commands you must add {@code "applications.commands"} to these scopes. The scope {@code "bot"} is always applied.

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

@@ -16,6 +16,9 @@
 
 package net.dv8tion.jda.api.entities;
 
+import net.dv8tion.jda.api.requests.RestAction;
+
+import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import java.time.OffsetDateTime;
@@ -104,8 +107,6 @@ default String getGuildId()
 
     /**
      * The type of the Entitlement
-     * <br>The only possible type of Entitlement currently is {@link EntitlementType#APPLICATION_SUBSCRIPTION}
-     * <br>Discord doesn't currently support other types for entitlements.
      *
      * @return the {@link Entitlement Entitlement} type
      */
@@ -137,11 +138,60 @@ default String getGuildId()
     @Nullable
     OffsetDateTime getTimeEnding();
 
+    /**
+     * Whether the {@link Entitlement Entitlement} was consumed or not.
+     *
+     * @return True if the {@link Entitlement Entitlement} was consumed, False otherwise
+     */
+    boolean isConsumed();
+
+    /**
+     * Consumes the {@link Entitlement Entitlement} if it has not already been consumed.
+     * <br>Only One-Time Purchase consumable {@link Entitlement Entitlements} can be consumed.
+     * <br>After the {@link Entitlement Entitlement} has been consumed, it will be marked as consumed.
+     *
+     * @return A {@link RestAction} that will consume the {@link Entitlement Entitlement}
+     */
+    @Nonnull
+    @CheckReturnValue
+    RestAction<Void> consume();
+
     /**
      * Represents the type of this Entitlement
      */
     enum EntitlementType
     {
+        /**
+         * Entitlement was purchased by user
+         */
+        PURCHASE(1),
+        /**
+         * Entitlement for Discord Nitro subscription
+         */
+        PREMIUM_SUBSCRIPTION(2),
+        /**
+         * Entitlement was gifted by developer
+         */
+        DEVELOPER_GIFT(3),
+        /**
+         * Entitlement was purchased by a dev in application test mode
+         */
+        TEST_MODE_PURCHASE(4),
+        /**
+         * Entitlement was granted when the SKU was free
+         */
+        FREE_PURCHASE(5),
+        /**
+         * Entitlement was gifted by another user
+         */
+        USER_GIFT(6),
+        /**
+         * Entitlement was claimed by user for free as a Nitro Subscriber
+         */
+        PREMIUM_PURCHASE(7),
+        /**
+         * 	Entitlement was purchased as an app subscription
+         */
         APPLICATION_SUBSCRIPTION(8),
         /**
          * Placeholder for unsupported types.

src/main/java/net/dv8tion/jda/api/requests/Route.java

@@ -46,6 +46,10 @@ public static class Applications
         public static final Route GET_ROLE_CONNECTION_METADATA =    new Route(GET, "applications/{application_id}/role-connections/metadata");
         public static final Route UPDATE_ROLE_CONNECTION_METADATA = new Route(PUT, "applications/{application_id}/role-connections/metadata");
         public static final Route GET_ENTITLEMENTS =                new Route(GET, "applications/{application_id}/entitlements");
+        public static final Route GET_ENTITLEMENT =                 new Route(GET, "applications/{application_id}/entitlements/{entitlement_id}");
+        public static final Route CONSUME_ENTITLEMENT =             new Route(POST, "applications/{application_id}/entitlements/{entitlement_id}/consume");
+        public static final Route CREATE_TEST_ENTITLEMENT =         new Route(POST, "applications/{application_id}/entitlements");
+        public static final Route DELETE_TEST_ENTITLEMENT =         new Route(DELETE, "applications/{application_id}/entitlements/{entitlement_id}");
     }
 
     public static class Interactions

src/main/java/net/dv8tion/jda/api/requests/restaction/TestEntitlementCreateAction.java

@@ -0,0 +1,137 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.api.requests.restaction;
+
+import net.dv8tion.jda.api.entities.Entitlement;
+import net.dv8tion.jda.api.requests.RestAction;
+import net.dv8tion.jda.api.utils.MiscUtil;
+
+import javax.annotation.CheckReturnValue;
+import javax.annotation.Nonnull;
+
+/**
+ * Extension of {@link net.dv8tion.jda.api.requests.RestAction RestAction} specifically
+ * designed to create a {@link Entitlement Entitlement}.
+ * This extension allows setting properties before executing the action.
+ *
+ * @see    net.dv8tion.jda.api.JDA
+ * @see    net.dv8tion.jda.api.JDA#createTestEntitlement(long, long, OwnerType)
+ */
+public interface TestEntitlementCreateAction extends RestAction<Entitlement>
+{
+
+    /**
+     * Set the SKU's id to create the entitlement in
+     *
+     * @param skuId
+     *        The id of the SKU
+     *
+     * @throws IllegalArgumentException
+     *         If the provided skuId is not a valid snowflake
+     *
+     * @return The current {@link TestEntitlementCreateAction} for chaining convenience
+     */
+    @CheckReturnValue
+    @Nonnull
+    default TestEntitlementCreateAction setSkuId(@Nonnull String skuId)
+    {
+        return setSkuId(MiscUtil.parseSnowflake(skuId));
+    }
+
+    /**
+     * Set the SKU's id to create the entitlement in
+     *
+     * @param skuId
+     *        The id of the SKU
+     *
+     * @return The current {@link TestEntitlementCreateAction} for chaining convenience
+     */
+    @CheckReturnValue
+    @Nonnull
+    TestEntitlementCreateAction setSkuId(long skuId);
+
+    /**
+     * Set the owner's id to create the entitlement for
+     *
+     * @param ownerId
+     *        The id of the owner - either guild id or user id
+     *
+     * @throws IllegalArgumentException
+     *         If the provided ownerId is not a valid snowflake
+     *
+     * @return The current {@link TestEntitlementCreateAction} for chaining convenience
+     */
+    @CheckReturnValue
+    @Nonnull
+    default TestEntitlementCreateAction setOwnerId(@Nonnull String ownerId)
+    {
+        return setOwnerId(MiscUtil.parseSnowflake(ownerId));
+    }
+
+    /**
+     * Set the owner's id to create the entitlement for
+     *
+     * @param ownerId
+     *        The id of the owner - either guild id or user id
+     *
+     * @return The current {@link TestEntitlementCreateAction} for chaining convenience
+     */
+    @CheckReturnValue
+    @Nonnull
+    TestEntitlementCreateAction setOwnerId(long ownerId);
+
+    /**
+     * Set the owner type to create the entitlement for
+     *
+     * @param type
+     *        The type of the owner
+     *
+     * @throws IllegalArgumentException
+     *         If the provided type is null
+     *
+     * @return The current {@link TestEntitlementCreateAction} for chaining convenience
+     */
+    @CheckReturnValue
+    @Nonnull
+    TestEntitlementCreateAction setOwnerType(@Nonnull OwnerType type);
+
+    /**
+     * The type of the owner for the entitlement
+     */
+    enum OwnerType
+    {
+        GUILD_SUBSCRIPTION(1),
+        USER_SUBSCRIPTION(2);
+
+        private final int key;
+
+        OwnerType(int key)
+        {
+            this.key = key;
+        }
+
+        /**
+         * The Discord defined id key for this OwnerType.
+         *
+         * @return the id key.
+         */
+        public int getKey()
+        {
+            return key;
+        }
+    }
+}