Reworked pets to deprecate enums & use pet endpoint

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

@@ -7,6 +7,8 @@
 import net.hypixel.api.http.HTTPQueryParams;
 import net.hypixel.api.http.HypixelHttpClient;
 import net.hypixel.api.http.HypixelHttpResponse;
+import net.hypixel.api.pets.IPetRepository;
+import net.hypixel.api.pets.impl.PetRepositoryImpl;
 import net.hypixel.api.reply.*;
 import net.hypixel.api.reply.skyblock.*;
 import net.hypixel.api.reply.skyblock.bingo.SkyBlockBingoDataReply;
@@ -222,6 +224,11 @@ public CompletableFuture<ResourceReply> getResource(String resource) {
         return requestResource(resource);
     }
 
+    public CompletableFuture<IPetRepository> getPetRepository() {
+        return getResource(ResourceType.VANITY_PETS)
+                .thenApply(PetRepositoryImpl::new);
+    }
+
     public CompletableFuture<SkyBlockProfileReply> getSkyBlockProfile(String profile) {
         return get(SkyBlockProfileReply.class, "skyblock/profile",
                 HTTPQueryParams.create()

hypixel-api-core/src/main/java/net/hypixel/api/pets/IPetRarity.java

@@ -0,0 +1,23 @@
+package net.hypixel.api.pets;
+
+public interface IPetRarity {
+
+    /**
+     * Retrieves the name of this pet rarity.
+     * This is only for pets and should not be mistaken with {@link net.hypixel.api.util.Rarity}.
+     * Even though they currently are the same values, this might change in the future and should be used accordingly.
+     *
+     * @return the name of this rarity
+     */
+    String getName();
+
+    /**
+     * Retrieves the color of this pet rarity
+     * This is only for pets and should not be mistaken with {@link net.hypixel.api.util.Rarity}.
+     * Even though they currently are the same values, this might change in the future and should be used accordingly.
+     *
+     * @return the color of this rarity
+     */
+    String getColor();
+
+}

hypixel-api-core/src/main/java/net/hypixel/api/pets/IPetRepository.java

@@ -0,0 +1,65 @@
+package net.hypixel.api.pets;
+
+import net.hypixel.api.reply.PlayerReply.Player;
+
+import java.util.Collection;
+
+public interface IPetRepository {
+
+    /**
+     * Gets the pet type associated with the provided key parameter
+     * A pet type is an object holding the pet's key, name, rarity and package.
+     *
+     * @param key the key of the pet
+     * @return {@code null} if no pet type matches the key, otherwise the pet type associated with that key
+     */
+    IPetType getTypeByKey(String key);
+
+    /**
+     * Gets the pet type associated with the provided package parameter
+     * A pet type is an object holding the pet's key, name, rarity and package.
+     *
+     * @param typePackage the package of the pet
+     * @return {@code null} if using
+     * {@link net.hypixel.api.pets.impl.compatibility.BackwardsCompatibilityPetRepositoryImpl} or if no pet type
+     * matches the package, otherwise the pet type associated with that package
+     */
+    IPetType getTypeByPackage(String typePackage);
+
+    /**
+     * Lists all pets matching the given {@link IPetRarity}
+     *
+     * @param rarity The rarity of the pets
+     * @return A collection (usually a {@link java.util.Set}) that contains all matched pets. If no pets are found,
+     * this returns an empty collection.
+     */
+    Collection<IPetType> getTypesForRarity(IPetRarity rarity);
+
+    /**
+     * Gets the pet rarity matching the provided name
+     *
+     * @param name the name of the rarity
+     * @return {@code null} if no rarity matches the provided name, otherwise returns the matched rarity
+     */
+    IPetRarity getRarityByName(String name);
+
+    /**
+     * Gets if a player has unlocked the specified {@link IPetType}
+     *
+     * @param type the pet type the player must have
+     * @param player the player to check against
+     * @return {@code true} if the player has unlocked the pet, otherwise {@code false}
+     */
+    boolean hasPlayerUnlocked(IPetType type, Player player);
+
+    /**
+     * @return a collection of all the cached rarities
+     */
+    Collection<IPetRarity> getRarities();
+
+    /**
+     * @return a collection of all the cached pet types
+     */
+    Collection<IPetType> getTypes();
+
+}

hypixel-api-core/src/main/java/net/hypixel/api/pets/IPetType.java

@@ -0,0 +1,29 @@
+package net.hypixel.api.pets;
+
+public interface IPetType {
+
+    /**
+     * @return the key of this pet type
+     */
+    String getKey();
+
+    /**
+     * @return the name of this pet type
+     */
+    String getName();
+
+    /**
+     * Note that the rarity can be {@code null}
+     *
+     * @return the rarity of this pet type
+     */
+    IPetRarity getRarity();
+
+    /**
+     * Note that the package is always {@code null} when using the backwards-compatible repository.
+     *
+     * @return the package of this pet type
+     */
+    String getPackage();
+
+}

hypixel-api-core/src/main/java/net/hypixel/api/pets/Pet.java

@@ -13,7 +13,7 @@ public class Pet {
             23210, 23750, 24280, 24830, 25380, 25930, 26500, 27070, 27640, 28220, 28810, 29400, 30000
     };
 
-    private Map<String, Object> stats;
+    private final Map<String, Object> stats;
     private int level;
     private int experience;
     private String name;
@@ -33,10 +33,20 @@ public Pet(Map<String, Object> stats) {
         updateLevel();
     }
 
+    /**
+     * Gets the custom name of the pet, if present
+     *
+     * @return {@code null} if no custom name has been set for the pet, otherwise returns the custom name
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Gets the average happiness, what we mean by "average happiness" is the mean value of all the {@link PetAttribute}
+     *
+     * @return the average happiness, with a min value of {@code 0.0}
+     */
     public double getAverageHappiness() {
         double attributeAverage = 0;
         for (PetAttribute attribute : PetAttribute.values()) {
@@ -46,6 +56,12 @@ public double getAverageHappiness() {
         return attributeAverage / PetAttribute.values().length;
     }
 
+    /**
+     * Gets the value associated with the attribute
+     *
+     * @param attribute the attribute
+     * @return the value associated with the value, or {@code 1} if not found or not a number
+     */
     public int getAttribute(PetAttribute attribute) {
         @SuppressWarnings("unchecked")
         Map<String, Object> attributeObject = (Map<String, Object>) stats.get(attribute.name());
@@ -71,6 +87,11 @@ public int getAttribute(PetAttribute attribute) {
         return Math.max(0, Math.round(value - iterations * attribute.getDecay()));
     }
 
+    /**
+     * Updates the cached level based on the experience
+     *
+     * @return {@code false} no matter what
+     */
     public boolean updateLevel() {
         int xp = experience;
         int level = 1;
@@ -86,10 +107,21 @@ public boolean updateLevel() {
         return false;
     }
 
+    /**
+     * Gets the level of this pet
+     *
+     * @return the level
+     */
     public int getLevel() {
         return level;
     }
 
+    /**
+     * Gets the experience required to level up to the provided level
+     *
+     * @param level the target level
+     * @return the experience amount required to reach the provided level
+     */
     public int getExperienceUntilLevel(int level) {
         int xp = 0;
         for (int i = 0; i < Math.min(level - 1, 100); i++) {
@@ -98,6 +130,11 @@ public int getExperienceUntilLevel(int level) {
         return xp;
     }
 
+    /**
+     * Gets the experience amount starting from the current level
+     *
+     * @return the current experience starting from the current level
+     */
     public int getLevelProgress() {
         return experience - getExperienceUntilLevel(level);
     }

hypixel-api-core/src/main/java/net/hypixel/api/pets/PetStats.java

@@ -1,27 +1,74 @@
 package net.hypixel.api.pets;
 
+import net.hypixel.api.pets.impl.compatibility.BackwardsCompatibilityPetRepositoryImpl;
+import net.hypixel.api.reply.PlayerReply;
+
 import java.util.HashMap;
 import java.util.Map;
 
 public class PetStats {
 
-    private Map<PetType, Pet> petMap = new HashMap<>();
+    private final Map<IPetType, Pet> petMap = new HashMap<>();
 
+    @Deprecated
     public PetStats(Map<String, Map<String, Object>> petStats) {
+        this(BackwardsCompatibilityPetRepositoryImpl.INSTANCE, petStats);
+    }
+
+    public PetStats(IPetRepository petRepository, Map<String, Map<String, Object>> petStats) {
         for (Map.Entry<String, Map<String, Object>> stringMapEntry : petStats.entrySet()) {
             try {
-                petMap.put(PetType.valueOf(stringMapEntry.getKey()), new Pet(stringMapEntry.getValue()));
+                petMap.put(petRepository.getTypeByKey(stringMapEntry.getKey()), new Pet(stringMapEntry.getValue()));
             } catch (IllegalArgumentException e) {
                 System.out.println("Invalid pet! " + stringMapEntry.getKey());
             }
         }
     }
 
-    public Pet getPet(PetType type) {
+    /**
+     * Gets a specific pet based on its pet type. Each player can only have one pet per type
+     *
+     * <b>Note:</b> If this returns {@code null}, it <b>doesn't</b> mean that the player hasn't unlocked the pet.
+     * What it does mean though, is that the player hasn't given any attributes nor a name to the pet
+     *
+     * To check if a player has unlocked a pet, use {@link IPetRepository#hasPlayerUnlocked(IPetType, PlayerReply.Player)}
+     *
+     * @param type the pet type to retrieve
+     * @return {@code null} if the player hasn't given a name and hasn't given any {@link PetAttribute},
+     * otherwise the {@link Pet} instance
+     */
+    public Pet getPet(IPetType type) {
         return petMap.get(type);
     }
 
+    /**
+     * Lists all the pets the player have
+     *
+     * @return a map filled with all the pets the player have
+     * @deprecated Use {@link #listAllPets()} instead
+     */
+    @Deprecated
     public Map<PetType, Pet> getAllPets() {
+        Map<PetType, Pet> oldPets = new HashMap<>();
+
+        for (Map.Entry<IPetType, Pet> entry : petMap.entrySet()) {
+            if (!(entry.getKey() instanceof PetType)) {
+                oldPets.clear();
+                throw new IllegalStateException("Cannot use #getAllPets when using the new pet repository. Please use #listAllPets");
+            }
+
+            oldPets.put((PetType) entry.getKey(), entry.getValue());
+        }
+
+        return oldPets;
+    }
+
+    /**
+     * Lists all the pets the player have
+     *
+     * @return a map filled with all the pets the player have
+     */
+    public Map<IPetType, Pet> listAllPets() {
         return petMap;
     }
 

hypixel-api-core/src/main/java/net/hypixel/api/pets/PetType.java

@@ -2,7 +2,12 @@
 
 import net.hypixel.api.util.Rarity;
 
-public enum PetType {
+/**
+ * The old and deprecated enum for the pet types
+ * @deprecated Consider using the {@link IPetRepository}
+ */
+@Deprecated
+public enum PetType implements IPetType {
 
     CAT_BLACK("Cat: Black", Rarity.COMMON),
     CAT_RED("Cat: Red", Rarity.COMMON),
@@ -127,6 +132,7 @@ public enum PetType {
 
     public static final PetType[] VALUES = values();
 
+    private final String key;
     private final String name;
     private final Rarity rarity;
 
@@ -135,15 +141,29 @@ public enum PetType {
     }
 
     PetType(String name, Rarity rarity) {
+        this.key = name();
         this.name = name;
         this.rarity = rarity;
     }
 
+    @Override
+    public String getKey() {
+        return key;
+    }
+
+    @Override
     public String getName() {
         return name;
     }
 
+    @Override
     public Rarity getRarity() {
         return rarity;
     }
+
+    @Override
+    public String getPackage() {
+        return null;
+    }
 }
+