Implement a RateLimit object to contain the rate limit headers in replies

hypixel-api-core/src/main/java/net/hypixel/api/HypixelAPI.java

@@ -154,6 +154,10 @@ public CompletableFuture<GuildReply> getGuildById(String id) {
         );
     }
 
+    /**
+     * @deprecated Endpoint is deprecated and will be removed on 14th August 2023.
+     */
+    @Deprecated
     public CompletableFuture<KeyReply> getKey() {
         return get(KeyReply.class, "key");
     }
@@ -304,7 +308,13 @@ private <R extends AbstractReply> CompletableFuture<R> get(Class<R> clazz, Strin
                     if (clazz == ResourceReply.class) {
                         return checkReply((R) new ResourceReply(Utilities.GSON.fromJson(response.getBody(), JsonObject.class)));
                     }
-                    return checkReply(Utilities.GSON.fromJson(response.getBody(), clazz));
+
+                    R reply = Utilities.GSON.fromJson(response.getBody(), clazz);
+                    if (reply instanceof RateLimitedReply) {
+                        ((RateLimitedReply) reply).setRateLimit(response.getRateLimit());
+                    }
+
+                    return checkReply(reply);
                 });
     }
 

hypixel-api-core/src/main/java/net/hypixel/api/http/HypixelHttpResponse.java

@@ -4,10 +4,17 @@ public class HypixelHttpResponse {
 
     private final int statusCode;
     private final String body;
+    private final RateLimit rateLimit;
 
+    @Deprecated
     public HypixelHttpResponse(int statusCode, String body) {
+        this(statusCode, body, null);
+    }
+
+    public HypixelHttpResponse(int statusCode, String body, RateLimit rateLimit) {
         this.statusCode = statusCode;
         this.body = body;
+        this.rateLimit = rateLimit;
     }
 
     public int getStatusCode() {
@@ -17,4 +24,8 @@ public int getStatusCode() {
     public String getBody() {
         return body;
     }
+
+    public RateLimit getRateLimit() {
+        return rateLimit;
+    }
 }

hypixel-api-core/src/main/java/net/hypixel/api/http/RateLimit.java

@@ -0,0 +1,57 @@
+package net.hypixel.api.http;
+
+import java.util.Date;
+import java.util.concurrent.TimeUnit;
+
+public class RateLimit {
+    private final int limit;
+    private final int remaining;
+    private final int reset;
+    private final Date resetAt;
+
+    public RateLimit(int limit, int remaining, int reset) {
+        this.limit = limit;
+        this.remaining = remaining;
+        this.reset = reset;
+        this.resetAt = new Date(System.currentTimeMillis() + TimeUnit.SECONDS.toMillis(reset));
+    }
+
+    /**
+     * @return the total limit allowed for the used API key per interval
+     */
+    public int getLimit() {
+        return limit;
+    }
+
+    /**
+     * @return the remaining amount of requests for the used API key during this interval
+     */
+    public int getRemaining() {
+        return remaining;
+    }
+
+    /**
+     * @return the time in seconds until the limit interval resets
+     */
+    public int getReset() {
+        return reset;
+    }
+
+    /**
+     * @return the date at which time the limit interval resets, this date won't be accurate to the millisecond due to
+     * the only context being in seconds
+     */
+    public Date getResetAt() {
+        return resetAt;
+    }
+
+    @Override
+    public String toString() {
+        return "RateLimit{" +
+                "limit=" + limit +
+                ", remaining=" + remaining +
+                ", reset=" + reset +
+                ", resetAt=" + resetAt +
+                '}';
+    }
+}

hypixel-api-core/src/main/java/net/hypixel/api/reply/BoostersReply.java

@@ -6,7 +6,7 @@
 import java.util.List;
 import java.util.UUID;
 
-public class BoostersReply extends AbstractReply {
+public class BoostersReply extends RateLimitedReply {
     private List<Booster> boosters;
     private BoosterState boosterState;
 

hypixel-api-core/src/main/java/net/hypixel/api/reply/CountsReply.java

@@ -2,7 +2,7 @@
 
 import java.util.Map;
 
-public class CountsReply extends AbstractReply {
+public class CountsReply extends RateLimitedReply {
     private Map<String, GameCount> games;
     private int playerCount;
 

hypixel-api-core/src/main/java/net/hypixel/api/reply/FindGuildReply.java

@@ -1,6 +1,6 @@
 package net.hypixel.api.reply;
 
-public class FindGuildReply extends AbstractReply {
+public class FindGuildReply extends RateLimitedReply {
     private String guild;
 
     /**

hypixel-api-core/src/main/java/net/hypixel/api/reply/GuildReply.java

@@ -1,22 +1,18 @@
 package net.hypixel.api.reply;
 
 import com.google.gson.annotations.SerializedName;
-import java.time.LocalDate;
-import java.time.ZonedDateTime;
-import java.util.Collections;
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.UUID;
 import net.hypixel.api.data.type.GameType;
 import net.hypixel.api.data.type.GuildAchievement;
 import net.hypixel.api.reply.PlayerReply.Player;
 import net.hypixel.api.util.Banner;
 
+import java.time.LocalDate;
+import java.time.ZonedDateTime;
+import java.util.*;
+
 // Suppressed because most fields are assigned by Gson via reflection.
 @SuppressWarnings({"unused", "RedundantSuppression", "MismatchedQueryAndUpdateOfCollection"})
-public class GuildReply extends AbstractReply {
+public class GuildReply extends RateLimitedReply {
 
     private Guild guild;
 

hypixel-api-core/src/main/java/net/hypixel/api/reply/KeyReply.java

@@ -4,7 +4,7 @@
 
 import java.util.UUID;
 
-public class KeyReply extends AbstractReply {
+public class KeyReply extends RateLimitedReply {
     private Key record;
 
     public Key getRecord() {

hypixel-api-core/src/main/java/net/hypixel/api/reply/LeaderboardsReply.java

@@ -6,7 +6,7 @@
 import java.util.Map;
 import java.util.UUID;
 
-public class LeaderboardsReply extends AbstractReply {
+public class LeaderboardsReply extends RateLimitedReply {
     private Map<GameType, List<Leaderboard>> leaderboards;
 
     public Map<GameType, List<Leaderboard>> getLeaderboards() {

hypixel-api-core/src/main/java/net/hypixel/api/reply/PlayerReply.java

@@ -16,7 +16,7 @@
 import java.util.Map;
 import java.util.UUID;
 
-public class PlayerReply extends AbstractReply {
+public class PlayerReply extends RateLimitedReply {
 
     // Suppressed because this field is dynamically assigned by Gson using reflection.
     @SuppressWarnings({"unused", "RedundantSuppression"})

hypixel-api-core/src/main/java/net/hypixel/api/reply/PunishmentStatsReply.java

@@ -2,7 +2,7 @@
 
 import com.google.gson.annotations.SerializedName;
 
-public class PunishmentStatsReply extends AbstractReply {
+public class PunishmentStatsReply extends RateLimitedReply {
     @SerializedName("staff_rollingDaily")
     private int staffRollingDaily;
     @SerializedName("staff_total")

hypixel-api-core/src/main/java/net/hypixel/api/reply/RateLimitedReply.java

@@ -0,0 +1,22 @@
+package net.hypixel.api.reply;
+
+import net.hypixel.api.http.RateLimit;
+
+public abstract class RateLimitedReply extends AbstractReply {
+    private RateLimit rateLimit;
+
+    public RateLimit getRateLimit() {
+        return rateLimit;
+    }
+
+    public void setRateLimit(RateLimit rateLimit) {
+        this.rateLimit = rateLimit;
+    }
+
+    @Override
+    public String toString() {
+        return "RateLimitedReply{" +
+                "rateLimit=" + rateLimit +
+                "} " + super.toString();
+    }
+}

hypixel-api-core/src/main/java/net/hypixel/api/reply/RecentGamesReply.java

@@ -5,7 +5,7 @@
 import java.time.ZonedDateTime;
 import java.util.List;
 
-public class RecentGamesReply extends AbstractReply {
+public class RecentGamesReply extends RateLimitedReply {
 
     private List<GameSession> games;
 

hypixel-api-core/src/main/java/net/hypixel/api/reply/StatusReply.java

@@ -3,7 +3,7 @@
 import com.google.gson.annotations.SerializedName;
 import net.hypixel.api.data.type.ServerType;
 
-public class StatusReply extends AbstractReply {
+public class StatusReply extends RateLimitedReply {
 
     /**
      * {@link StatusReply.Session} instance of player

hypixel-api-core/src/main/java/net/hypixel/api/reply/skyblock/SkyBlockNewsReply.java

@@ -2,9 +2,9 @@
 
 import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
-import net.hypixel.api.reply.AbstractReply;
+import net.hypixel.api.reply.RateLimitedReply;
 
-public class SkyBlockNewsReply extends AbstractReply {
+public class SkyBlockNewsReply extends RateLimitedReply {
     private JsonElement items;
 
     public JsonArray getItems() {

hypixel-api-core/src/main/java/net/hypixel/api/reply/skyblock/SkyBlockProfileReply.java

@@ -2,9 +2,9 @@
 
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
-import net.hypixel.api.reply.AbstractReply;
+import net.hypixel.api.reply.RateLimitedReply;
 
-public class SkyBlockProfileReply extends AbstractReply {
+public class SkyBlockProfileReply extends RateLimitedReply {
     private JsonElement profile;
 
     public JsonObject getProfile() {

hypixel-api-core/src/main/java/net/hypixel/api/reply/skyblock/SkyBlockProfilesReply.java

@@ -2,9 +2,9 @@
 
 import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
-import net.hypixel.api.reply.AbstractReply;
+import net.hypixel.api.reply.RateLimitedReply;
 
-public class SkyBlockProfilesReply extends AbstractReply {
+public class SkyBlockProfilesReply extends RateLimitedReply {
     private JsonElement profiles;
 
     public JsonArray getProfiles() {

hypixel-api-core/src/main/java/net/hypixel/api/reply/skyblock/bingo/SkyBlockBingoDataReply.java

@@ -1,10 +1,10 @@
 package net.hypixel.api.reply.skyblock.bingo;
 
-import net.hypixel.api.reply.AbstractReply;
+import net.hypixel.api.reply.RateLimitedReply;
 
 import java.util.List;
 
-public class SkyBlockBingoDataReply extends AbstractReply {
+public class SkyBlockBingoDataReply extends RateLimitedReply {
     private List<BingoEventData> events;
 
     public List<BingoEventData> getEvents() {

hypixel-api-example/src/main/java/net/hypixel/api/example/GetPlayerExample.java

@@ -121,5 +121,11 @@ public static void main(String[] args) {
          * `.getRaw()` method.
          */
         System.out.println("Raw JSON ------> " + player.getRaw());
+
+        /*
+         * RateLimit object is available to any reply from a request to an authenticated endpoint and returns context
+         * to the rate limit of the used API key.
+         */
+        System.out.println("Rate Limit ----> " + apiReply.getRateLimit());
     }
 }

hypixel-api-transport-apache/src/main/java/net/hypixel/api/apache/ApacheHttpClient.java

@@ -2,6 +2,7 @@
 
 import net.hypixel.api.http.HypixelHttpClient;
 import net.hypixel.api.http.HypixelHttpResponse;
+import net.hypixel.api.http.RateLimit;
 import org.apache.http.HttpResponse;
 import org.apache.http.client.HttpClient;
 import org.apache.http.client.methods.HttpGet;
@@ -31,7 +32,7 @@ public CompletableFuture<HypixelHttpResponse> makeRequest(String url) {
         return CompletableFuture.supplyAsync(() -> {
             try {
                 HttpResponse response = this.httpClient.execute(new HttpGet(url));
-                return new HypixelHttpResponse(response.getStatusLine().getStatusCode(), EntityUtils.toString(response.getEntity(), "UTF-8"));
+                return new HypixelHttpResponse(response.getStatusLine().getStatusCode(), EntityUtils.toString(response.getEntity(), "UTF-8"), null);
             } catch (IOException e) {
                 throw new RuntimeException(e);
             }
@@ -45,13 +46,24 @@ public CompletableFuture<HypixelHttpResponse> makeAuthenticatedRequest(String ur
             request.addHeader("API-Key", this.apiKey.toString());
             try {
                 HttpResponse response = this.httpClient.execute(request);
-                return new HypixelHttpResponse(response.getStatusLine().getStatusCode(), EntityUtils.toString(response.getEntity(), "UTF-8"));
+                return new HypixelHttpResponse(response.getStatusLine().getStatusCode(), EntityUtils.toString(response.getEntity(), "UTF-8"), createRateLimitResponse(response));
             } catch (IOException e) {
                 throw new RuntimeException(e);
             }
         }, this.executorService);
     }
 
+    private RateLimit createRateLimitResponse(HttpResponse response) {
+        if (response.getStatusLine().getStatusCode() != 200) {
+            return null;
+        }
+
+        int limit = Integer.parseInt(response.getFirstHeader("RateLimit-Limit").getValue());
+        int remaining = Integer.parseInt(response.getFirstHeader("RateLimit-Remaining").getValue());
+        int reset = Integer.parseInt(response.getFirstHeader("RateLimit-Reset").getValue());
+        return new RateLimit(limit, remaining, reset);
+    }
+
     @Override
     public void shutdown() {
         this.executorService.shutdown();