Added @Contract annotations for API methods

Enhanced method contracts with `@Contract` annotations to improve nullability and immutability handling while clarifying method behaviors.

Author: NonSwag

src/main/java/net/thenextlvl/service/api/economy/Account.java

@@ -3,6 +3,7 @@
 import net.thenextlvl.service.api.economy.currency.Currency;
 import net.thenextlvl.service.api.economy.currency.CurrencyHolder;
 import org.bukkit.World;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 import java.math.BigDecimal;
@@ -20,6 +21,7 @@ public interface Account extends Comparable<Account> {
      * @return the {@code CurrencyHolder} capable of managing currencies for the account
      */
     CurrencyHolder getController();
+    @Contract(pure = true)
 
     /**
      * Deposits the specified amount into the account balance.

src/main/java/net/thenextlvl/service/api/economy/EconomyController.java

@@ -6,6 +6,7 @@
 import net.thenextlvl.service.api.economy.currency.CurrencyHolder;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.World;
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NullMarked;
 
@@ -167,6 +168,7 @@ default CompletableFuture<Optional<Account>> tryGetAccount(UUID uuid, World worl
      * @return a CompletableFuture that will complete with the created account
      * @throws IllegalStateException if a similar account already exists
      */
+    @Contract("_ -> new")
     default CompletableFuture<Account> createAccount(OfflinePlayer player) {
         return createAccount(player.getUniqueId());
     }
@@ -178,7 +180,8 @@ default CompletableFuture<Account> createAccount(OfflinePlayer player) {
      * @param world  the world in which the player's account will be created
      * @return a CompletableFuture that will complete with the created account
      */
-    default CompletableFuture<Account> createAccount(OfflinePlayer player, World world) {
+    @Contract("_, _ -> new")
+    default CompletableFuture<Account> createAccount(OfflinePlayer player, @Nullable World world) {
         return createAccount(player.getUniqueId(), world);
     }
 
@@ -188,7 +191,10 @@ default CompletableFuture<Account> createAccount(OfflinePlayer player, World wor
      * @param uuid the uuid of the account to be created
      * @return a CompletableFuture that will complete with the created account
      */
-    CompletableFuture<Account> createAccount(UUID uuid);
+    @Contract("_ -> new")
+    default CompletableFuture<Account> createAccount(UUID uuid) {
+        return createAccount(uuid, null);
+    }
 
     /**
      * Creates an account with the given uuid and world.
@@ -197,7 +203,8 @@ default CompletableFuture<Account> createAccount(OfflinePlayer player, World wor
      * @param world the world in which the account will be created
      * @return a CompletableFuture that will complete with the created account
      */
-    CompletableFuture<Account> createAccount(UUID uuid, World world);
+    @Contract("_, _ -> new")
+    CompletableFuture<Account> createAccount(UUID uuid, @Nullable World world);
 
     /**
      * Loads the account for the specified player asynchronously.

src/main/java/net/thenextlvl/service/api/economy/bank/Bank.java

@@ -2,6 +2,7 @@
 
 import net.thenextlvl.service.api.economy.Account;
 import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NullMarked;
 
@@ -28,6 +29,7 @@ public interface Bank extends Account {
      *
      * @return the name of the bank.
      */
+    @Contract(pure = true)
     String getName();
 
     /**

src/main/java/net/thenextlvl/service/api/economy/bank/BankController.java

@@ -4,6 +4,7 @@
 import net.thenextlvl.service.api.economy.currency.CurrencyHolder;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.World;
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NullMarked;
 
@@ -23,6 +24,7 @@ public interface BankController extends Controller, CurrencyHolder {
      * @param name   the name of the bank (must be unique)
      * @return a CompletableFuture that completes with the created bank
      */
+    @Contract("_, _ -> new")
     default CompletableFuture<Bank> createBank(OfflinePlayer player, String name) {
         return createBank(player.getUniqueId(), name);
     }
@@ -37,7 +39,8 @@ default CompletableFuture<Bank> createBank(OfflinePlayer player, String name) {
      * @param world  the world in which the bank is located
      * @return a CompletableFuture that completes with the created bank
      */
-    default CompletableFuture<Bank> createBank(OfflinePlayer player, String name, World world) {
+    @Contract("_, _, _ -> new")
+    default CompletableFuture<Bank> createBank(OfflinePlayer player, String name, @Nullable World world) {
         return createBank(player.getUniqueId(), name, world);
     }
 
@@ -51,6 +54,7 @@ default CompletableFuture<Bank> createBank(OfflinePlayer player, String name, Wo
      * @return a CompletableFuture that completes with the created bank
      */
     CompletableFuture<Bank> createBank(UUID uuid, String name);
+    @Contract("_, _ -> new")
 
     /**
      * Creates a new bank with the provided UUID, name, and world.
@@ -63,6 +67,7 @@ default CompletableFuture<Bank> createBank(OfflinePlayer player, String name, Wo
      * @return a CompletableFuture that completes with the created bank
      */
     CompletableFuture<Bank> createBank(UUID uuid, String name, World world);
+    @Contract("_, _, _ -> new")
 
     /**
      * Loads a bank asynchronously with the specified player.

src/main/java/net/thenextlvl/service/api/economy/currency/Currency.java

@@ -4,6 +4,7 @@
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.text.Component;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 import java.util.Locale;
@@ -17,6 +18,7 @@ public interface Currency {
      *
      * @return the name of the currency as a string
      */
+    @Contract(pure = true)
     String getName();
 
     /**
@@ -112,6 +114,7 @@ interface Builder {
          * @param locale the locale for which the singular display name is being set
          * @return the builder instance for chaining
          */
+        @Contract(value = "_, _ -> this", pure = true)
         Builder displayNameSingular(Component name, Locale locale);
 
         /**
@@ -120,6 +123,7 @@ interface Builder {
          * @param locale the locale for which the singular display name should be retrieved
          * @return an {@code Optional} containing the singular display name as a {@code Component}, or empty
          */
+        @Contract(value = "_ -> new")
         Optional<Component> displayNameSingular(Locale locale);
 
         /**
@@ -129,6 +133,7 @@ interface Builder {
          * @param locale the locale for which the plural display name is being set
          * @return the builder instance for chaining
          */
+        @Contract(value = "_, _ -> this", pure = true)
         Builder displayNamePlural(Component name, Locale locale);
 
         /**
@@ -137,6 +142,7 @@ interface Builder {
          * @param locale the locale for which the plural display name should be retrieved
          * @return an {@code Optional} containing the plural display name as a {@code Component}, or empty
          */
+        @Contract(value = "_ -> new")
         Optional<Component> displayNamePlural(Locale locale);
 
         /**
@@ -145,13 +151,15 @@ interface Builder {
          * @param symbol the symbol component to represent the currency
          * @return the builder instance for chaining
          */
+        @Contract(value = "_ -> this", pure = true)
         Builder symbol(Component symbol);
 
         /**
          * Retrieves the currency symbol set on the {@code Builder}.
          *
          * @return an {@code Optional} containing the symbol as a {@code Component}, or empty
          */
+        @Contract(value = "-> new")
         Optional<Component> symbol();
 
         /**
@@ -164,6 +172,7 @@ interface Builder {
          * @return the builder instance for chaining
          * @throws IllegalArgumentException if {@code fractionalDigits} is negative
          */
+        @Contract(value = "_ -> this")
         Builder fractionalDigits(int fractionalDigits) throws IllegalArgumentException;
 
         /**
@@ -174,13 +183,15 @@ interface Builder {
          *
          * @return an {@code OptionalInt} containing the number of fractional digits, or empty
          */
+        @Contract(value = "-> new")
         OptionalInt fractionalDigits();
 
         /**
          * Builds and returns a {@link Currency} instance based on the properties set on the {@code Builder}.
          *
          * @return the constructed {@link Currency} instance
          */
+        @Contract("-> new")
         @ApiStatus.OverrideOnly
         Currency build();
     }

src/main/java/net/thenextlvl/service/api/economy/currency/CurrencyHolder.java

@@ -1,6 +1,7 @@
 package net.thenextlvl.service.api.economy.currency;
 
 import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Locale;
@@ -83,6 +84,7 @@ default boolean hasCurrency(String name) {
      * @throws UnsupportedOperationException if {@link #hasMultiCurrencySupport()} is {@code false}
      * @since 3.0.0
      */
+    @Contract("_, _ -> new")
     default Optional<Currency> createCurrency(String name, Consumer<Currency.Builder> builder) {
         throw new UnsupportedOperationException("Not implemented yet");
     }
@@ -105,6 +107,7 @@ default boolean deleteCurrency(String name) {
      * @return the default currency
      * @since 3.0.0
      */
+    @Contract(pure = true)
     Currency getDefaultCurrency();
 
     /**
@@ -119,6 +122,7 @@ default boolean deleteCurrency(String name) {
      * @see #hasCurrency(String)
      * @since 3.0.0
      */
+    @Contract(pure = true)
     default boolean hasMultiCurrencySupport() {
         return false;
     }