Add support for premium app subscriptions

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

@@ -0,0 +1,203 @@
+/*
+ * 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.entities;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.time.OffsetDateTime;
+
+/**
+ * Represents a Discord Entitlement for premium App subscriptions.
+ * <br>This should contain all information provided from Discord about an {@link Entitlement Entitlement}.
+ */
+public interface Entitlement extends ISnowflake
+{
+    /**
+     * The id of the entitlement
+     *
+     * @return The id of the {@link Entitlement Entitlement}
+     */
+    @Override
+    long getIdLong();
+
+    /**
+     * The id of the SKU related to this {@link Entitlement Entitlement}
+     *
+     * @return The id of the SKU related to this {@link Entitlement Entitlement}
+     */
+    long getSkuIdLong();
+
+    /**
+     * The id of the SKU related to this {@link Entitlement Entitlement}
+     *
+     * @return The id of the SKU related to this {@link Entitlement Entitlement}
+     */
+    @Nonnull
+    default String getSkuId()
+    {
+        return Long.toUnsignedString(getSkuIdLong());
+    }
+
+    /**
+     * The id of the parent application of this {@link Entitlement Entitlement}
+     *
+     * @return The id of the parent application of this {@link Entitlement Entitlement}
+     */
+    long getApplicationIdLong();
+
+    /**
+     * The id of the parent application of this {@link Entitlement Entitlement}
+     *
+     * @return The id of the parent application of this {@link Entitlement Entitlement}
+     */
+    @Nonnull
+    default String getApplicationId()
+    {
+        return Long.toUnsignedString(getApplicationIdLong());
+    }
+
+    /**
+     * The id of the user that purchased the {@link Entitlement Entitlement}
+     *
+     * @return The id of the user that purchased the {@link Entitlement Entitlement}
+     */
+    @Nullable
+    Long getUserIdLong();
+
+    /**
+     * The id of the user that purchased the {@link Entitlement Entitlement}
+     *
+     * @return The id of the user that purchased the {@link Entitlement Entitlement}
+     */
+    @Nullable
+    default String getUserId()
+    {
+        if (getUserIdLong() == null) {
+            return null;
+        }
+
+        return Long.toUnsignedString(getUserIdLong());
+    }
+
+    /**
+     * The guild id that is granted access to the {@link Entitlement Entitlement}'s SKU
+     *
+     * @return The id of the guild that is granted access to the {@link Entitlement Entitlement}'s SKU,
+     * or {@code null} if this entitlement is related to a subscription of type "User Subscription"
+     */
+    @Nullable
+    Long getGuildIdLong();
+
+    /**
+     * The guild id that is granted access to the {@link Entitlement Entitlement}'s SKU
+     *
+     * @return The id of the guild that is granted access to the {@link Entitlement Entitlement}'s SKU,
+     * or {@code null} if this entitlement is related to a subscription of type "User Subscription"
+     */
+    @Nullable
+    default String getGuildId()
+    {
+        if (getGuildIdLong() == null) {
+            return null;
+        }
+
+        return Long.toUnsignedString(getGuildIdLong());
+    }
+
+    /**
+     * 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
+     */
+    @Nonnull
+    EntitlementType getType();
+
+    /**
+     * Whether the {@link Entitlement Entitlement} has been deleted or not.
+     *
+     * @return True if the {@link Entitlement Entitlement} was deleted, False otherwise
+     *
+     * @see    net.dv8tion.jda.api.events.entitlement.EntitlementDeleteEvent
+     */
+    boolean isDeleted();
+
+    /**
+     * The start date at which the {@link Entitlement Entitlement} is valid.
+     *
+     * @return Start date at which the {@link Entitlement Entitlement} is valid. Not present when using test entitlements.
+     */
+    @Nullable
+    OffsetDateTime getStartsAt();
+
+    /**
+     * Date at which the {@link Entitlement Entitlement} is no longer valid.
+     *
+     * @return Date at which the {@link Entitlement Entitlement} is no longer valid. Not present when using test entitlements.
+     */
+    @Nullable
+    OffsetDateTime getEndsAt();
+
+    /**
+     * Represents the type of this Entitlement
+     */
+    enum EntitlementType {
+        APPLICATION_SUBSCRIPTION(8),
+        /**
+         * Placeholder for unsupported types.
+         */
+        UNKNOWN(-1);
+
+        private final int key;
+
+        EntitlementType(int key)
+        {
+            this.key = key;
+        }
+
+        /**
+         * The Discord defined id key for this EntitlementType.
+         *
+         * @return the id key.
+         */
+        public int getKey()
+        {
+            return key;
+        }
+
+        /**
+         * Gets the EntitlementType related to the provided key.
+         * <br>If an unknown key is provided, this returns {@link #UNKNOWN}
+         *
+         * @param  key
+         *         The Discord key referencing a EntitlementType.
+         *
+         * @return The EntitlementType that has the key provided, or {@link #UNKNOWN} for unknown key.
+         */
+        @Nonnull
+        public static EntitlementType fromKey(int key)
+        {
+            for (EntitlementType type : values())
+            {
+                if (type.getKey() == key)
+                    return type;
+            }
+            return UNKNOWN;
+        }
+    }
+}

src/main/java/net/dv8tion/jda/api/events/entitlement/EntitlementCreateEvent.java

@@ -0,0 +1,35 @@
+/*
+ * 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.events.entitlement;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Entitlement;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Indicates that a user subscribed to a SKU.
+ *
+ * @see #getEntitlement()
+ */
+public class EntitlementCreateEvent extends GenericEntitlementEvent
+{
+    public EntitlementCreateEvent(@Nonnull JDA api, long responseNumber, @Nonnull Entitlement entitlement)
+    {
+        super(api, responseNumber, entitlement);
+    }
+}

src/main/java/net/dv8tion/jda/api/events/entitlement/EntitlementDeleteEvent.java

@@ -0,0 +1,45 @@
+/*
+ * 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.events.entitlement;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Entitlement;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Indicates a user's entitlement is deleted. Entitlement deletions are infrequent, and occur when:
+ * <ul>
+ *     <li>Discord issues a refund for a subscription</li>
+ *     <li>Discord removes an entitlement from a user via internal tooling</li>
+ * </ul>
+ * <p><b>Notice</b><br>
+ * Entitlements are not deleted when they expire.
+ * <br>
+ * If a user's subscription is cancelled, you will not receive an {@link EntitlementDeleteEvent EntitlementDeleteEvent}.
+ * <br>Instead, you will simply not receive an {@link EntitlementUpdateEvent EntitlementUpdateEvent} with a new {@link Entitlement#getEndsAt() endsAt} date at the end of the billing period.
+ *
+ * @see #getEntitlement()
+ * @see EntitlementUpdateEvent
+ */
+public class EntitlementDeleteEvent extends GenericEntitlementEvent
+{
+    public EntitlementDeleteEvent(@Nonnull JDA api, long responseNumber, @Nonnull Entitlement entitlement)
+    {
+        super(api, responseNumber, entitlement);
+    }
+}

src/main/java/net/dv8tion/jda/api/events/entitlement/EntitlementUpdateEvent.java

@@ -0,0 +1,40 @@
+/*
+ * 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.events.entitlement;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Entitlement;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Indicates a user's subscription has renewed for the next billing period.
+ * The {@link Entitlement#getEndsAt() endsAt} field will have an updated value with the new expiration date.
+ *
+ * <p><b>Notice</b><br>
+ * If a user's subscription is cancelled, you will not receive an {@link EntitlementDeleteEvent EntitlementDeleteEvent}.
+ * <br>Instead, you will simply not receive an {@link EntitlementUpdateEvent EntitlementUpdateEvent} with a new {@link Entitlement#getEndsAt() endsAt} date at the end of the billing period.
+ *
+ * @see #getEntitlement()
+ */
+public class EntitlementUpdateEvent extends GenericEntitlementEvent
+{
+    public EntitlementUpdateEvent(@Nonnull JDA api, long responseNumber, @Nonnull Entitlement entitlement)
+    {
+        super(api, responseNumber, entitlement);
+    }
+}

src/main/java/net/dv8tion/jda/api/events/entitlement/GenericEntitlementEvent.java

@@ -0,0 +1,46 @@
+/*
+ * 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.events.entitlement;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Entitlement;
+import net.dv8tion.jda.api.events.Event;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Indicates that an {@link Entitlement Entitlement} was either created, updated or deleted
+ *
+ * @see EntitlementCreateEvent
+ * @see EntitlementUpdateEvent
+ * @see EntitlementDeleteEvent
+ */
+public abstract class GenericEntitlementEvent extends Event
+{
+    protected final Entitlement entitlement;
+
+    GenericEntitlementEvent(@Nonnull JDA api, long responseNumber, @Nonnull Entitlement entitlement) {
+        super(api, responseNumber);
+        this.entitlement = entitlement;
+    }
+
+    @Nonnull
+    public Entitlement getEntitlement()
+    {
+        return entitlement;
+    }
+}

src/main/java/net/dv8tion/jda/api/events/entitlement/package-info.java

@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+
+/**
+ * Events that indicate that a {@link net.dv8tion.jda.api.entities.Entitlement Entitlement}
+ * is either created, updated or deleted.
+ */
+package net.dv8tion.jda.api.events.entitlement;