Implement invite targets

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

@@ -137,11 +137,21 @@ static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String
     /**
      * The type of this invite.
      *
-     * @return The invites's type
+     * @return The invite's type
      */
     @Nonnull
     Invite.InviteType getType();
 
+    /**
+     * The target type of this invite or {@link TargetType#NONE} if this invite does not have a {@link #getTarget() InviteTarget}.
+     *
+     * @return The invite's target type or {@link TargetType#NONE}
+     *
+     * @see    Invite.TargetType
+     */
+    @Nonnull
+    Invite.TargetType getTargetType();
+
     /**
      * An {@link net.dv8tion.jda.api.entities.Invite.Channel Invite.Channel} object
      * containing information about this invite's origin channel.
@@ -153,14 +163,6 @@ static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String
     @Nullable
     Channel getChannel();
 
-    /**
-     * The invite code
-     *
-     * @return the invite code
-     */
-    @Nonnull
-    String getCode();
-
     /**
      * An {@link net.dv8tion.jda.api.entities.Invite.Group Invite.Group} object
      * containing information about this invite's origin group.
@@ -172,6 +174,26 @@ static RestAction<Invite> resolve(@Nonnull final JDA api, @Nonnull final String
     @Nullable
     Group getGroup();
 
+    /**
+     * An {@link Invite.InviteTarget Invite.InviteTarget} object
+     * containing information about this invite's target or {@code null}
+     * if this invite does not have a target.
+     *
+     * @return Information about this invite's target or {@code null}
+     *
+     * @see    net.dv8tion.jda.api.entities.Invite.InviteTarget
+     */
+    @Nullable
+    InviteTarget getTarget();
+
+    /**
+     * The invite code
+     *
+     * @return the invite code
+     */
+    @Nonnull
+    String getCode();
+
     /**
      * The invite URL for this invite in the format of:
      * {@code "https://discord.gg/" + getCode()}
@@ -329,7 +351,7 @@ interface Channel extends ISnowflake
         /**
          * The name of this channel.
          *
-         * @return The channels's name
+         * @return The channel's name
          */
         @Nonnull
         String getName();
@@ -374,7 +396,7 @@ interface Guild extends ISnowflake
         /**
          * The name of this guild.
          *
-         * @return The guilds's name
+         * @return The guild's name
          */
         @Nonnull
         String getName();
@@ -486,12 +508,129 @@ interface Group extends ISnowflake
          * {@link #resolve(net.dv8tion.jda.api.JDA, java.lang.String, boolean) Invite.resolve()} method with the
          * {@code withCounts} boolean set to {@code true}.
          *
-         * @return The names of the groups's users or null if not preset in the invite
+         * @return The names of the group's users or null if not preset in the invite
          */
         @Nullable
         List<String> getUsers();
     }
 
+    /**
+     * POJO for the target of this invite.
+     *
+     * @see #getTarget()
+     */
+    interface InviteTarget
+    {
+
+        /**
+         * The type of this invite target.
+         *
+         * @return The type of this invite target
+         */
+        @Nonnull
+        TargetType getType();
+
+        /**
+         * The Snowflake id of the target entity of this invite.
+         *
+         * @throws IllegalStateException
+         *         If there is no target entity, {@link #getType() TargetType} is {@link TargetType#UNKNOWN}
+         *
+         * @return The id of the target entity
+         */
+        @Nonnull
+        String getId();
+
+        /**
+         * The Snowflake id of the target entity of this invite.
+         *
+         * @throws IllegalStateException
+         *         If there is no target entity, {@link #getType() TargetType} is {@link TargetType#UNKNOWN}
+         *
+         * @return The id of the target entity
+         */
+        long getIdLong();
+
+        /**
+         * The target {@link User} of this invite or {@code null} if the {@link #getType() TargeType} is not {@link TargetType#STREAM}
+         *
+         * @return The target user of this invite
+         *
+         * @see    net.dv8tion.jda.api.entities.User
+         */
+        @Nullable
+        User getUser();
+
+        /**
+         * The target {@link EmbeddedApplication} of this invite or {@code null} if the {@link #getType() TargeType} is not {@link TargetType#EMBEDDED_APPLICATION}
+         *
+         * @return The target application of this invite
+         *
+         * @see    net.dv8tion.jda.api.entities.Invite.EmbeddedApplication
+         */
+        @Nullable
+        EmbeddedApplication getApplication();
+    }
+
+    /**
+     * POJO for the target application information provided by an invite.
+     *
+     * @see InviteTarget#getApplication()
+     */
+    interface EmbeddedApplication extends ISnowflake
+    {
+        /**
+         * The name of this application.
+         *
+         * @return The name of this application.
+         */
+        @Nonnull
+        String getName();
+
+        /**
+         * The description of this application.
+         *
+         * @return The description of this application.
+         */
+        @Nonnull
+        String getDescription();
+
+        /**
+         * The summary of this application or {@code null} if this application has no summary.
+         *
+         * @return The summary of this application.
+         */
+        @Nullable
+        String getSummary();
+
+        /**
+         * The icon id of this application or {@code null} if the application has no icon.
+         *
+         * @return The application's icon id
+         *
+         * @see    #getIconUrl()
+         */
+        @Nullable
+        String getIconId();
+
+        /**
+         * The icon url of this application or {@code null} if the application has no icon.
+         *
+         * @return The application's icon url
+         *
+         * @see    #getIconId()
+         */
+        @Nullable
+        String getIconUrl();
+
+        /**
+         * The max participant count of this application or {@code -1} if no max participant count is set
+         *
+         * @return {@code -1} if this application does not have a max participant count
+         */
+        int getMaxParticipants();
+    }
+
     /**
      * Enum representing the type of an invite.
      *
@@ -503,4 +642,78 @@ enum InviteType
         GROUP,
         UNKNOWN
     }
+
+    /**
+     * A TargetType indicates additional action to be taken by the client on accepting the invite,
+     * typically connecting external services or launching external applications depending on the specific TargetType.
+     *
+     * Some actions might not be available or show up on certain devices.
+     *
+     * @see InviteTarget#getType()
+     */
+    enum TargetType
+    {
+        /**
+         * The invite does not have a target type, {@link Invite#getTarget()} will return {@code null}.
+         */
+        NONE(0),
+
+        /**
+         * The invite points to a user's stream in a voice channel.
+         * The user to whose stream the invite goes can be get with {@link InviteTarget#getUser() InviteTarget.getUser} and is not {@code null}.
+         *
+         * @see InviteTarget#getUser()
+         */
+        STREAM(1),
+
+        /**
+         * The invite points to an application in a voice channel.
+         * The application to which the invite goes can be get with {@link InviteTarget#getApplication() InviteTarget.getApplication} and is not {@code null}.
+         *
+         * @see InviteTarget#getApplication()
+         */
+        EMBEDDED_APPLICATION(2),
+
+        /**
+         * 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.
+         */
+        UNKNOWN(-1);
+
+        private final int id;
+
+        TargetType(int id)
+        {
+            this.id = id;
+        }
+
+        /**
+         * The Discord id key used to represent the target type.
+         *
+         * @return The id key used by discord for this channel type.
+         */
+        public int getId()
+        {
+            return id;
+        }
+
+        /**
+         * Static accessor for retrieving a target type based on its Discord id key.
+         *
+         * @param  id
+         *         The id key of the requested target type.
+         *
+         * @return The TargetType that is referred to by the provided key. If the id key is unknown, {@link #UNKNOWN} is returned.
+         */
+        @Nonnull
+        public static TargetType fromId(int id)
+        {
+            for (TargetType type : values())
+            {
+                if (type.id == id)
+                    return type;
+            }
+            return UNKNOWN;
+        }
+    }
 }