Add parcel return feature

src/main/java/com/eternalcode/parcellockers/ParcelLockers.java

@@ -44,6 +44,11 @@
 import com.eternalcode.parcellockers.parcel.service.ParcelService;
 import com.eternalcode.parcellockers.parcel.service.ParcelServiceImpl;
 import com.eternalcode.parcellockers.parcel.task.ParcelSendTask;
+import com.eternalcode.parcellockers.returns.ParcelReturnService;
+import com.eternalcode.parcellockers.returns.ParcelReturnValidator;
+import com.eternalcode.parcellockers.returns.ReturnItemEquivalence;
+import com.eternalcode.parcellockers.returns.repository.CollectedParcelRepositoryOrmLite;
+import com.eternalcode.parcellockers.returns.task.ReturnWindowPurgeTask;
 import com.eternalcode.parcellockers.updater.UpdaterService;
 import com.eternalcode.parcellockers.user.UserManager;
 import com.eternalcode.parcellockers.user.UserManagerImpl;
@@ -122,12 +127,14 @@ public void onEnable() {
         DeliveryRepositoryOrmLite deliveryRepository = new DeliveryRepositoryOrmLite(databaseManager, scheduler);
         ItemStorageRepository itemStorageRepository = new ItemStorageRepositoryOrmLite(databaseManager, scheduler);
         UserRepository userRepository = new UserRepositoryOrmLite(databaseManager, scheduler);
+        CollectedParcelRepositoryOrmLite collectedParcelRepository = new CollectedParcelRepositoryOrmLite(databaseManager, scheduler);
 
         // service and managers
         ParcelService parcelService = new ParcelServiceImpl(
             noticeService,
             parcelRepository,
             parcelContentRepository,
+            collectedParcelRepository,
             scheduler,
             config,
             this.economy,
@@ -152,6 +159,27 @@ public void onEnable() {
             noticeService
         );
 
+        ParcelReturnValidator returnValidator = new ParcelReturnValidator(new ReturnItemEquivalence(config.settings.returnChecks));
+        ParcelReturnService parcelReturnService = new ParcelReturnService(
+            parcelService,
+            parcelContentManager,
+            collectedParcelRepository,
+            deliveryManager,
+            lockerManager,
+            returnValidator,
+            scheduler,
+            config,
+            noticeService,
+            this.economy,
+            server
+        );
+
+        scheduler.timerAsync(
+            new ReturnWindowPurgeTask(parcelService, collectedParcelRepository, config),
+            Duration.ofSeconds(30),
+            Duration.ofMinutes(30)
+        );
+
         // guis
         TriumphGui.init(this);
         GuiManager guiManager = new GuiManager(
@@ -162,7 +190,8 @@ public void onEnable() {
             parcelDispatchService,
             parcelContentManager,
             deliveryManager,
-            config.settings.allowCollectingFromAnyLocker
+            config.settings.allowCollectingFromAnyLocker,
+            parcelReturnService
         );
 
         MainGui mainGUI = new MainGui(
@@ -177,7 +206,8 @@ public void onEnable() {
             scheduler,
             config.guiSettings,
             guiManager,
-            noticeService
+            noticeService,
+            config.settings.parcelReturnWindow
         );
 
         AdminParcelService adminParcelService = new AdminParcelService(

src/main/java/com/eternalcode/parcellockers/configuration/implementation/MessageConfig.java

@@ -125,6 +125,26 @@ public static class ParcelMessages extends OkaeriConfig {
             .chat("&2✔ &a${AMOUNT} has been withdrawn from your account to cover the parcel sending fee.")
             .sound(SoundEventKeys.ENTITY_EXPERIENCE_ORB_PICKUP)
             .build();
+        public Notice returned = Notice.builder()
+            .chat("&2✔ &aParcel returned. It is on its way back to the sender.")
+            .sound(SoundEventKeys.ENTITY_PLAYER_LEVELUP)
+            .build();
+        public Notice cannotReturn = Notice.builder()
+            .chat("&4✘ &cThis parcel cannot be returned right now. Your items were given back.")
+            .sound(SoundEventKeys.ENTITY_VILLAGER_NO)
+            .build();
+        public Notice returnItemsMismatch = Notice.builder()
+            .chat("&4✘ &cThe deposited items do not match the original parcel contents!")
+            .sound(SoundEventKeys.ENTITY_VILLAGER_NO)
+            .build();
+        public Notice returnWindowExpired = Notice.builder()
+            .chat("&4✘ &cThe return window for this parcel has expired!")
+            .sound(SoundEventKeys.ENTITY_VILLAGER_NO)
+            .build();
+        public Notice returnFeeWithdrawn = Notice.builder()
+            .chat("&2✔ &a${AMOUNT} has been withdrawn from your account to cover the parcel return fee.")
+            .sound(SoundEventKeys.ENTITY_EXPERIENCE_ORB_PICKUP)
+            .build();
 
         @Comment({"", "# The parcel info message." })
         public Notice parcelInfoMessages = Notice.builder()

src/main/java/com/eternalcode/parcellockers/configuration/implementation/PluginConfig.java

@@ -94,6 +94,25 @@ public static class Settings extends OkaeriConfig {
 
         @Comment({"", "# Large parcel fee in in-game currency"})
         public double largeParcelFee = 50.0;
+
+        @Comment({"", "# How long after collection a parcel can still be returned.", "# Expired collected parcels are purged periodically."})
+        public Duration parcelReturnWindow = Duration.ofDays(7);
+
+        @Comment({"", "# Small parcel return fee in in-game currency"})
+        public double smallParcelReturnFee = 5.0;
+
+        @Comment({"", "# Medium parcel return fee in in-game currency"})
+        public double mediumParcelReturnFee = 12.5;
+
+        @Comment({"", "# Large parcel return fee in in-game currency"})
+        public double largeParcelReturnFee = 25.0;
+
+        @Comment({
+            "",
+            "# Which item attributes must match the original parcel content when a player returns a parcel.",
+            "# Material types and total amounts must always match; each flag below relaxes one attribute when set to false."
+        })
+        public ReturnChecks returnChecks = new ReturnChecks();
     }
 
     public static class GuiSettings extends OkaeriConfig {
@@ -490,6 +509,66 @@ public static class GuiSettings extends OkaeriConfig {
 
         @Comment({ "", "# The lore line showing when the parcel has arrived. Placeholders: {DATE} - arrival date" })
         public String parcelArrivedLine = "&aArrived on: &2{DATE}";
+
+        @Comment({ "", "# The title of the parcel return GUI" })
+        public String parcelReturnGuiTitle = "&5Return parcels";
+
+        @Comment({ "", "# The title of the return deposit GUI" })
+        public String parcelReturnDepositGuiTitle = "&5Deposit the parcel items";
+
+        @Comment({ "", "# The item of the parcel locker return button" })
+        public ConfigItem parcelLockerReturnItem = new ConfigItem()
+            .name("&5↩ Return parcels")
+            .lore(List.of("&5» &dClick to return a collected parcel."))
+            .type(Material.HOPPER)
+            .glow(true);
+
+        @Comment({ "", "# The item of the parcel in the return GUI" })
+        public ConfigItem parcelReturnRowItem = new ConfigItem()
+            .name("&d{NAME}")
+            .lore(List.of(
+                    "&6Sender: &e{SENDER}",
+                    "&6Size: &e{SIZE}",
+                    "&6Description: &e{DESCRIPTION}"
+                )
+            )
+            .type(Material.CHEST_MINECART);
+
+        @Comment({ "", "# The item displayed in the return GUI when there is nothing to return" })
+        public ConfigItem noReturnableParcelsItem = new ConfigItem()
+            .name("&4✘ &cNo returnable parcels")
+            .lore(List.of("&cYou don't have any parcels to return."))
+            .type(Material.STRUCTURE_VOID);
+
+        @Comment({ "", "# The item of the confirm return button" })
+        public ConfigItem confirmReturnItem = new ConfigItem()
+            .name("&2✔ &aConfirm return")
+            .lore(List.of("&2» &aDeposit the original items above, then click to return the parcel."))
+            .type(Material.GREEN_DYE);
+
+        @Comment({ "", "# The lore line showing how long the parcel can still be returned. Placeholder: {DURATION}" })
+        public String returnWindowRemainingLine = "&5Return window: &d{DURATION} left";
+
+        @Comment({ "", "# The lore line shown when the return window has expired." })
+        public String returnWindowExpiredLine = "&cReturn window expired";
+    }
+
+    public static class ReturnChecks extends OkaeriConfig {
+
+        @Comment("# Whether durability (damage) must match the original items.")
+        public boolean checkDurability = true;
+
+        @Comment("# Whether custom display names must match the original items.")
+        public boolean checkItemName = true;
+
+        @Comment("# Whether enchantments must match the original items.")
+        public boolean checkEnchantments = true;
+
+        @Comment("# Whether lore must match the original items.")
+        public boolean checkLore = true;
+
+        @Comment({"# Whether all remaining item data (NBT) must match the original items.", "# When false, only the attributes enabled above are compared."})
+        public boolean checkNbt = true;
     }
 
     public static class DiscordSettings extends OkaeriConfig {

src/main/java/com/eternalcode/parcellockers/gui/GuiManager.java

@@ -12,6 +12,8 @@
 import com.eternalcode.parcellockers.parcel.Parcel;
 import com.eternalcode.parcellockers.parcel.service.ParcelDispatchService;
 import com.eternalcode.parcellockers.parcel.service.ParcelService;
+import com.eternalcode.parcellockers.returns.CollectedParcel;
+import com.eternalcode.parcellockers.returns.ParcelReturnService;
 import com.eternalcode.parcellockers.shared.Page;
 import com.eternalcode.parcellockers.shared.PageResult;
 import com.eternalcode.parcellockers.user.User;
@@ -35,6 +37,7 @@ public class GuiManager {
     private final ParcelContentManager parcelContentManager;
     private final DeliveryManager deliveryManager;
     private final boolean allowCollectingFromAnyLocker;
+    private final ParcelReturnService parcelReturnService;
 
     public GuiManager(
         ParcelService parcelService,
@@ -44,7 +47,8 @@ public GuiManager(
         ParcelDispatchService parcelDispatchService,
         ParcelContentManager parcelContentManager,
         DeliveryManager deliveryManager,
-        boolean allowCollectingFromAnyLocker
+        boolean allowCollectingFromAnyLocker,
+        ParcelReturnService parcelReturnService
     ) {
         this.parcelService = parcelService;
         this.lockerManager = lockerManager;
@@ -54,6 +58,7 @@ public GuiManager(
         this.parcelContentManager = parcelContentManager;
         this.deliveryManager = deliveryManager;
         this.allowCollectingFromAnyLocker = allowCollectingFromAnyLocker;
+        this.parcelReturnService = parcelReturnService;
     }
 
     /**
@@ -157,4 +162,16 @@ public CompletableFuture<Void> deleteAllParcels(CommandSender sender, NoticeServ
     public CompletableFuture<Void> deleteAllLockers(CommandSender sender, NoticeService noticeService) {
         return this.lockerManager.deleteAll(sender, noticeService);
     }
+
+    public CompletableFuture<PageResult<Parcel>> getReturnableParcels(UUID receiver, Page page) {
+        return this.parcelService.getReturnable(receiver, page);
+    }
+
+    public CompletableFuture<Optional<CollectedParcel>> getCollectedInfo(UUID parcelId) {
+        return this.parcelReturnService.getCollectedInfo(parcelId);
+    }
+
+    public void returnParcel(Player player, Parcel parcel, List<ItemStack> deposited) {
+        this.parcelReturnService.returnParcel(player, parcel, deposited);
+    }
 }

src/main/java/com/eternalcode/parcellockers/gui/implementation/locker/ItemStorageGui.java

@@ -11,6 +11,7 @@
 import dev.triumphteam.gui.guis.Gui;
 import dev.triumphteam.gui.guis.GuiItem;
 import dev.triumphteam.gui.guis.StorageGui;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.stream.IntStream;
@@ -26,21 +27,24 @@ public class ItemStorageGui {
     private final GuiManager guiManager;
     private final NoticeService noticeService;
     private final SendingGuiState state;
+    private final Duration returnWindow;
 
     public ItemStorageGui(
         Scheduler scheduler,
         GuiSettings guiSettings,
         MiniMessage miniMessage,
         GuiManager guiManager,
         NoticeService noticeService,
-        SendingGuiState state
+        SendingGuiState state,
+        Duration returnWindow
     ) {
         this.scheduler = scheduler;
         this.guiSettings = guiSettings;
         this.miniMessage = miniMessage;
         this.guiManager = guiManager;
         this.noticeService = noticeService;
         this.state = state;
+        this.returnWindow = returnWindow;
     }
 
     void show(Player player, ParcelSize size) {
@@ -111,7 +115,8 @@ void show(Player player, ParcelSize size) {
                     this.miniMessage,
                     this.noticeService,
                     this.guiManager,
-                    this.state
+                    this.state,
+                    this.returnWindow
                 ).show(player))
                 .exceptionally(throwable -> {
                     // Persisting the staged items failed; hand them back so they are not lost.

src/main/java/com/eternalcode/parcellockers/gui/implementation/locker/LockerGui.java

@@ -9,6 +9,7 @@
 import com.eternalcode.parcellockers.notification.NoticeService;
 import dev.triumphteam.gui.guis.Gui;
 import dev.triumphteam.gui.guis.GuiItem;
+import java.time.Duration;
 import java.util.UUID;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.minimessage.MiniMessage;
@@ -21,17 +22,19 @@ public class LockerGui implements GuiView {
     private final GuiSettings guiSettings;
     private final GuiManager guiManager;
     private final NoticeService noticeService;
+    private final Duration returnWindow;
 
     public LockerGui(
         MiniMessage miniMessage, Scheduler scheduler,
         GuiSettings guiSettings, GuiManager guiManager,
-        NoticeService noticeService
+        NoticeService noticeService, Duration returnWindow
     ) {
         this.miniMessage = miniMessage;
         this.scheduler = scheduler;
         this.guiSettings = guiSettings;
         this.guiManager = guiManager;
         this.noticeService = noticeService;
+        this.returnWindow = returnWindow;
     }
 
     public void show(Player player, UUID entryLocker) {
@@ -53,14 +56,25 @@ public void show(Player player, UUID entryLocker) {
             entryLocker
         );
 
+        ReturnGui returnGui = new ReturnGui(
+            this.guiSettings,
+            this.scheduler,
+            this.guiManager,
+            this.miniMessage,
+            this.noticeService,
+            this.returnWindow
+        );
+
         gui.setItem(21, this.guiSettings.parcelLockerCollectItem.toGuiItem(event -> collectionGui.show(player)));
+        gui.setItem(22, this.guiSettings.parcelLockerReturnItem.toGuiItem(event -> returnGui.show(player)));
         gui.setItem(23, this.guiSettings.parcelLockerSendItem.toGuiItem(event -> new SendingGui(
             this.scheduler,
             this.guiSettings,
             this.miniMessage,
             this.noticeService,
             this.guiManager,
-            new SendingGuiState().entryLocker(entryLocker)
+            new SendingGuiState().entryLocker(entryLocker),
+            this.returnWindow
         ).show(player, entryLocker)));
 
         gui.open(player);