MailboxGUI Developer API

package com.rismr1.mailboxgui.api;

import com.rismr1.mailboxgui.api.request.BookLetterMailRequest;
import com.rismr1.mailboxgui.api.request.LetterMailRequest;
import com.rismr1.mailboxgui.api.request.MailboxApiRecipient;
import com.rismr1.mailboxgui.api.request.MoneyMailRequest;
import com.rismr1.mailboxgui.api.request.PackageMailRequest;
import com.rismr1.mailboxgui.api.result.MailboxSendResult;
import com.rismr1.mailboxgui.api.model.MailboxApiInfo;
import com.rismr1.mailboxgui.api.service.MailboxInboxApi;
import com.rismr1.mailboxgui.api.service.MailboxItemCodecApi;
import com.rismr1.mailboxgui.api.service.MailboxNotificationApi;
import com.rismr1.mailboxgui.api.service.MailboxRegistryApi;
import com.rismr1.mailboxgui.api.service.MailboxScheduledMailApi;
import com.rismr1.mailboxgui.api.service.MailboxTrackingApi;

import java.util.Optional;
import java.util.UUID;

public interface MailboxGUIApi {

    String API_VERSION = "2.0";

    MailboxSendResult sendLetter(LetterMailRequest request);

    MailboxSendResult sendBookLetter(BookLetterMailRequest request);

    MailboxSendResult sendPackage(PackageMailRequest request);

    MailboxSendResult sendMoney(MoneyMailRequest request);

    Optional<MailboxApiRecipient> findRecipientByName(String playerName);

    boolean hasMailboxData(UUID playerUuid);

    boolean hasRegisteredMailbox(UUID playerUuid);

    int getUncheckedMailCount(UUID playerUuid);

    int getPendingLoginNotificationCount(UUID playerUuid);

    boolean hasPendingMailNotification(UUID playerUuid);

    boolean refreshMailNotification(UUID playerUuid);

    boolean clearMailNotification(UUID playerUuid);

    int getPackageContentLimit();

    default MailboxApiInfo getApiInfo() {
        return new MailboxApiInfo(API_VERSION, "unknown", "unknown", true, getPackageContentLimit(), java.util.Set.of());
    }

    default MailboxInboxApi inbox() {
        throw new UnsupportedOperationException("Inbox API is not available from this provider.");
    }

    default MailboxTrackingApi tracking() {
        throw new UnsupportedOperationException("Tracking API is not available from this provider.");
    }

    default MailboxScheduledMailApi scheduledMail() {
        throw new UnsupportedOperationException("Scheduled Mail API is not available from this provider.");
    }

    default MailboxRegistryApi registry() {
        throw new UnsupportedOperationException("Mailbox registry API is not available from this provider.");
    }

    default MailboxItemCodecApi itemCodecs() {
        throw new UnsupportedOperationException("Custom item codec API is not available from this provider.");
    }

    default MailboxNotificationApi notifications() {
        throw new UnsupportedOperationException("Notification provider API is not available from this provider.");
    }

    default com.rismr1.mailboxgui.api.service.MailboxResourcePackApi resourcePacks() {
        throw new UnsupportedOperationException("Resource-pack status API is not available from this provider.");
    }
}

package com.rismr1.mailboxgui.api;

import org.bukkit.Bukkit;

public final class MailboxGUIApiProvider {

    private MailboxGUIApiProvider() {
    }

    public static MailboxGUIApi get() {
        return Bukkit.getServicesManager().load(MailboxGUIApi.class);
    }
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.model.InboxMailEntry;
import com.rismr1.mailboxgui.api.model.InboxPage;
import com.rismr1.mailboxgui.api.model.InboxQuery;
import com.rismr1.mailboxgui.api.model.MailMutationResult;
import com.rismr1.mailboxgui.api.type.ApiOperationStatus;
import org.bukkit.entity.Player;

import java.util.Optional;
import java.util.UUID;

public interface MailboxInboxApi {
    InboxPage query(UUID ownerUuid, InboxQuery query);

    Optional<InboxMailEntry> findById(UUID ownerUuid, String mailId);

    MailMutationResult delete(UUID ownerUuid, String mailId, long expectedRevision, String reason);

    MailMutationResult claimMoney(UUID ownerUuid, String mailId, long expectedRevision, Player recipient);

    MailMutationResult claimPackageContents(UUID ownerUuid, String mailId, long expectedRevision, Player recipient);

    /**
     * Opens MailboxGUI's secure package workflow, including COD acceptance when applicable.
     */
    ApiOperationStatus openPackageManagement(UUID ownerUuid, String mailId, long expectedRevision,
                                             Player recipient, int returnPage);
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.model.DelayedMailEntry;
import com.rismr1.mailboxgui.api.type.ApiOperationStatus;
import com.rismr1.mailboxgui.api.type.MailLifecycleStatus;

import java.util.List;
import java.util.Optional;
import java.util.UUID;

public interface MailboxTrackingApi {
    List<DelayedMailEntry> getPending(UUID recipientUuid);

    /**
     * Returns the current status while mail is pending delivery or remains in the inbox.
     * Completed historical states are emitted through MailboxMailLifecycleEvent.
     */
    Optional<MailLifecycleStatus> getCurrentStatus(UUID recipientUuid, String mailOrQueueId);

    ApiOperationStatus cancel(String queueId);
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.model.ScheduledMailRunResult;
import com.rismr1.mailboxgui.api.model.ScheduledMailTask;
import com.rismr1.mailboxgui.api.type.ApiOperationStatus;

import java.util.List;
import java.util.Map;
import java.util.Optional;

public interface MailboxScheduledMailApi {
    List<ScheduledMailTask> getTasks();

    Optional<ScheduledMailTask> getTask(String id);

    ApiOperationStatus upsertTask(String id, Map<String, Object> definition);

    ApiOperationStatus removeTask(String id);

    ApiOperationStatus setEnabled(String id, boolean enabled);

    ScheduledMailRunResult runNow(String id);

    void reload();
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.model.PublicAccessNpc;
import com.rismr1.mailboxgui.api.model.PublicMailbox;
import com.rismr1.mailboxgui.api.model.RegisteredMailbox;

import java.util.List;
import java.util.UUID;

public interface MailboxRegistryApi {
    List<RegisteredMailbox> getPlayerMailboxes();

    List<RegisteredMailbox> getPlayerMailboxes(UUID ownerUuid);

    List<PublicMailbox> getPublicMailboxes();

    List<PublicAccessNpc> getPublicAccessNpcs();
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.spi.CustomItemCodec;
import org.bukkit.inventory.ItemStack;

import java.util.List;

public interface MailboxItemCodecApi {
    boolean register(CustomItemCodec codec);

    boolean unregister(String codecId);

    List<String> getRegisteredCodecIds();

    ItemStack prepareForStorage(ItemStack item);

    ItemStack restoreAfterStorage(ItemStack item);

    boolean isSupportedOnCurrentBackend(ItemStack item);
}

package com.rismr1.mailboxgui.api.service;

import com.rismr1.mailboxgui.api.spi.MailNotificationProvider;

import java.util.List;

public interface MailboxNotificationApi {
    boolean register(MailNotificationProvider provider);

    boolean unregister(String providerId);

    List<String> getRegisteredProviderIds();
}

package com.rismr1.mailboxgui.api.service;

import org.bukkit.plugin.Plugin;
import java.time.Duration;
import java.util.UUID;

/** Optional, provider-owned confirmations for GUI appearance; available in both editions. */
public interface MailboxResourcePackApi {
    /**
     * Reports a confirmed load (or removes that pack's confirmation) for an online local player.
     * Call on the server main thread. Loaded confirmations expire after validity (1 second to 2 minutes);
     * refresh them while the pack remains loaded. False removes only this provider's specified pack.
     * The supplying plugin must authenticate any remote reports before calling this trusted local API.
     * Returns false if the source is disabled, the player is offline, or identifiers/validity are invalid.
     * This does not deliver a pack, verify its assets, change player preferences or enable customization.
     */
    boolean report(Plugin source, UUID playerId, UUID packId, boolean loaded, Duration validity);

    /** Clears this provider's confirmations for one player. Main thread only. */
    void clear(Plugin source, UUID playerId);

    /** Clears all confirmations owned by this provider. Main thread only. */
    void clear(Plugin source);
}

package com.rismr1.mailboxgui.api.request;

import java.util.Objects;
import java.util.UUID;

public final class MailboxApiRecipient {

    private final UUID uuid;
    private final String name;

    private MailboxApiRecipient(UUID uuid, String name) {
        this.uuid = uuid;
        this.name = normalizeName(name);
    }

    public static MailboxApiRecipient of(UUID uuid, String name) {
        if (uuid == null && (name == null || name.isBlank())) {
            throw new IllegalArgumentException("A recipient must have a UUID, name, or both.");
        }
        return new MailboxApiRecipient(uuid, name);
    }

    public static MailboxApiRecipient uuid(UUID uuid) {
        Objects.requireNonNull(uuid, "uuid");
        return new MailboxApiRecipient(uuid, null);
    }

    public static MailboxApiRecipient name(String name) {
        if (name == null || name.isBlank()) {
            throw new IllegalArgumentException("name cannot be blank");
        }
        return new MailboxApiRecipient(null, name);
    }

    public UUID getUuid() {
        return uuid;
    }

    public String getName() {
        return name;
    }

    public boolean hasUuid() {
        return uuid != null;
    }

    public boolean hasName() {
        return name != null && !name.isBlank();
    }

    private static String normalizeName(String input) {
        if (input == null) {
            return null;
        }

        String trimmed = input.trim();
        return trimmed.isEmpty() ? null : trimmed;
    }
}

package com.rismr1.mailboxgui.api.request;

import com.rismr1.mailboxgui.api.type.RecipientPolicy;
import com.rismr1.mailboxgui.api.type.NetworkDeliveryTarget;

import java.time.Duration;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

public final class LetterMailRequest {

    private final List<MailboxApiRecipient> recipients;
    private final String fromDisplayName;
    private final String message;
    private final int deliveryDelaySeconds;
    private final boolean notifyRecipients;
    private final RecipientPolicy recipientPolicy;
    private final String sourcePluginName;
    private final long expirationDurationSeconds;
    private final NetworkDeliveryTarget networkDeliveryTarget;

    private LetterMailRequest(Builder builder) {
        this.recipients = Collections.unmodifiableList(new ArrayList<>(builder.recipients));
        this.fromDisplayName = normalize(builder.fromDisplayName);
        this.message = builder.message == null ? "" : builder.message;
        this.deliveryDelaySeconds = builder.deliveryDelaySeconds;
        this.notifyRecipients = builder.notifyRecipients;
        this.recipientPolicy = builder.recipientPolicy;
        this.sourcePluginName = normalize(builder.sourcePluginName);
        this.expirationDurationSeconds = builder.expirationDurationSeconds;
        this.networkDeliveryTarget = builder.networkDeliveryTarget == null ? NetworkDeliveryTarget.wholeNetwork() : builder.networkDeliveryTarget;
    }

    public static Builder builder() {
        return new Builder();
    }

    public List<MailboxApiRecipient> getRecipients() {
        return recipients;
    }

    public String getFromDisplayName() {
        return fromDisplayName;
    }

    public String getMessage() {
        return message;
    }

    public int getDeliveryDelaySeconds() {
        return deliveryDelaySeconds;
    }

    public boolean isNotifyRecipients() {
        return notifyRecipients;
    }

    public RecipientPolicy getRecipientPolicy() {
        return recipientPolicy;
    }

    public String getSourcePluginName() {
        return sourcePluginName;
    }

    /**
     * Requested expiration duration in seconds. Zero means non-expiring; delayed mail starts this duration at actual delivery.
     */
    public long getExpirationDurationSeconds() {
        return expirationDurationSeconds;
    }

    public boolean hasExpiration() {
        return expirationDurationSeconds > 0L;
    }

    public NetworkDeliveryTarget getNetworkDeliveryTarget() {
        return networkDeliveryTarget;
    }

    private static String normalize(String input) {
        if (input == null) {
            return null;
        }
        String trimmed = input.trim();
        return trimmed.isEmpty() ? null : trimmed;
    }

    public static final class Builder {
        private final List<MailboxApiRecipient> recipients = new ArrayList<>();
        private String fromDisplayName;
        private String message;
        private int deliveryDelaySeconds = -1;
        private boolean notifyRecipients = true;
        private RecipientPolicy recipientPolicy = RecipientPolicy.KNOWN_MAILBOXGUI_PLAYER;
        private String sourcePluginName;
        private long expirationDurationSeconds;
        private NetworkDeliveryTarget networkDeliveryTarget = NetworkDeliveryTarget.wholeNetwork();

        public Builder recipient(UUID uuid, String name) {
            this.recipients.add(MailboxApiRecipient.of(uuid, name));
            return this;
        }

        public Builder recipient(UUID uuid) {
            this.recipients.add(MailboxApiRecipient.uuid(uuid));
            return this;
        }

        public Builder recipient(String name) {
            this.recipients.add(MailboxApiRecipient.name(name));
            return this;
        }

        public Builder recipients(List<MailboxApiRecipient> recipients) {
            if (recipients != null) {
                this.recipients.addAll(recipients);
            }
            return this;
        }

        public Builder fromDisplayName(String fromDisplayName) {
            this.fromDisplayName = fromDisplayName;
            return this;
        }

        public Builder message(String message) {
            this.message = message;
            return this;
        }

        public Builder deliveryDelaySeconds(int deliveryDelaySeconds) {
            this.deliveryDelaySeconds = deliveryDelaySeconds;
            return this;
        }

        public Builder notifyRecipients(boolean notifyRecipients) {
            this.notifyRecipients = notifyRecipients;
            return this;
        }

        public Builder recipientPolicy(RecipientPolicy recipientPolicy) {
            if (recipientPolicy != null) {
                this.recipientPolicy = recipientPolicy;
            }
            return this;
        }

        public Builder sourcePluginName(String sourcePluginName) {
            this.sourcePluginName = sourcePluginName;
            return this;
        }

        public Builder expirationDurationSeconds(long seconds) {
            this.expirationDurationSeconds = validateExpirationSeconds(seconds);
            return this;
        }

        public Builder expiresAfter(Duration duration) {
            this.expirationDurationSeconds = validateExpirationDuration(duration);
            return this;
        }

        public Builder networkDeliveryTarget(NetworkDeliveryTarget target) {
            this.networkDeliveryTarget = target == null ? NetworkDeliveryTarget.wholeNetwork() : target;
            return this;
        }

        public LetterMailRequest build() {
            return new LetterMailRequest(this);
        }
    }

    private static long validateExpirationSeconds(long seconds) {
        if (seconds < 0L) {
            throw new IllegalArgumentException("expirationDurationSeconds cannot be negative.");
        }
        Math.multiplyExact(seconds, 1000L);
        return seconds;
    }

    private static long validateExpirationDuration(Duration duration) {
        if (duration == null || duration.isZero() || duration.isNegative()) {
            throw new IllegalArgumentException("Expiration duration must be positive.");
        }
        long seconds = duration.getSeconds();
        if (seconds <= 0L) {
            throw new IllegalArgumentException("Expiration duration must be at least one second.");
        }
        return validateExpirationSeconds(seconds);
    }
}

package com.rismr1.mailboxgui.api.request;

import com.rismr1.mailboxgui.api.type.RecipientPolicy;
import com.rismr1.mailboxgui.api.type.NetworkDeliveryTarget;

import java.time.Duration;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

public final class BookLetterMailRequest {

    private final List<MailboxApiRecipient> recipients;
    private final String fromDisplayName;
    private final String title;
    private final String message;
    private final int deliveryDelaySeconds;
    private final boolean notifyRecipients;
    private final RecipientPolicy recipientPolicy;
    private final String sourcePluginName;
    private final long expirationDurationSeconds;
    private final NetworkDeliveryTarget networkDeliveryTarget;

    private BookLetterMailRequest(Builder builder) {
        this.recipients = Collections.unmodifiableList(new ArrayList<>(builder.recipients));
        this.fromDisplayName = normalize(builder.fromDisplayName);
        this.title = normalize(builder.title);
        this.message = builder.message == null ? "" : builder.message;
        this.deliveryDelaySeconds = builder.deliveryDelaySeconds;
        this.notifyRecipients = builder.notifyRecipients;
        this.recipientPolicy = builder.recipientPolicy;
        this.sourcePluginName = normalize(builder.sourcePluginName);
        this.expirationDurationSeconds = builder.expirationDurationSeconds;
        this.networkDeliveryTarget = builder.networkDeliveryTarget == null ? NetworkDeliveryTarget.wholeNetwork() : builder.networkDeliveryTarget;
    }

    public static Builder builder() {
        return new Builder();
    }

    public List<MailboxApiRecipient> getRecipients() {
        return recipients;
    }

    public String getFromDisplayName() {
        return fromDisplayName;
    }

    public String getTitle() {
        return title;
    }

    public String getMessage() {
        return message;
    }

    public int getDeliveryDelaySeconds() {
        return deliveryDelaySeconds;
    }

    public boolean isNotifyRecipients() {
        return notifyRecipients;
    }

    public RecipientPolicy getRecipientPolicy() {
        return recipientPolicy;
    }

    public String getSourcePluginName() {
        return sourcePluginName;
    }

    /**
     * Requested expiration duration in seconds. Zero means non-expiring; delayed mail starts this duration at actual delivery.
     */
    public long getExpirationDurationSeconds() {
        return expirationDurationSeconds;
    }

    public boolean hasExpiration() {
        return expirationDurationSeconds > 0L;
    }

    public NetworkDeliveryTarget getNetworkDeliveryTarget() {
        return networkDeliveryTarget;
    }

    private static String normalize(String input) {
        if (input == null) {
            return null;
        }

        String trimmed = input.trim();
        return trimmed.isEmpty() ? null : trimmed;
    }

    public static final class Builder {
        private final List<MailboxApiRecipient> recipients = new ArrayList<>();
        private String fromDisplayName;
        private String title;
        private String message;
        private int deliveryDelaySeconds = -1;
        private boolean notifyRecipients = true;
        private RecipientPolicy recipientPolicy = RecipientPolicy.KNOWN_MAILBOXGUI_PLAYER;
        private String sourcePluginName;
        private long expirationDurationSeconds;
        private NetworkDeliveryTarget networkDeliveryTarget = NetworkDeliveryTarget.wholeNetwork();

        public Builder recipient(UUID uuid, String name) {
            this.recipients.add(MailboxApiRecipient.of(uuid, name));
            return this;
        }

        public Builder recipient(UUID uuid) {
            this.recipients.add(MailboxApiRecipient.uuid(uuid));
            return this;
        }

        public Builder recipient(String name) {
            this.recipients.add(MailboxApiRecipient.name(name));
            return this;
        }

        public Builder recipients(List<MailboxApiRecipient> recipients) {
            if (recipients != null) {
                this.recipients.addAll(recipients);
            }
            return this;
        }

        public Builder fromDisplayName(String fromDisplayName) {
            this.fromDisplayName = fromDisplayName;
            return this;
        }

        public Builder title(String title) {
            this.title = title;
            return this;
        }

        public Builder message(String message) {
            this.message = message;
            return this;
        }

        public Builder deliveryDelaySeconds(int deliveryDelaySeconds) {
            this.deliveryDelaySeconds = deliveryDelaySeconds;
            return this;
        }

        public Builder notifyRecipients(boolean notifyRecipients) {
            this.notifyRecipients = notifyRecipients;
            return this;
        }

        public Builder recipientPolicy(RecipientPolicy recipientPolicy) {
            if (recipientPolicy != null) {
                this.recipientPolicy = recipientPolicy;
            }
            return this;
        }

        public Builder sourcePluginName(String sourcePluginName) {
            this.sourcePluginName = sourcePluginName;
            return this;
        }

        public Builder expirationDurationSeconds(long seconds) {
            this.expirationDurationSeconds = validateExpirationSeconds(seconds);
            return this;
        }

        public Builder expiresAfter(Duration duration) {
            this.expirationDurationSeconds = validateExpirationDuration(duration);
            return this;
        }

        public Builder networkDeliveryTarget(NetworkDeliveryTarget target) {
            this.networkDeliveryTarget = target == null ? NetworkDeliveryTarget.wholeNetwork() : target;
            return this;
        }

        public BookLetterMailRequest build() {
            return new BookLetterMailRequest(this);
        }
    }

    private static long validateExpirationSeconds(long seconds) {
        if (seconds < 0L) {
            throw new IllegalArgumentException("expirationDurationSeconds cannot be negative.");
        }
        Math.multiplyExact(seconds, 1000L);
        return seconds;
    }

    private static long validateExpirationDuration(Duration duration) {
        if (duration == null || duration.isZero() || duration.isNegative()) {
            throw new IllegalArgumentException("Expiration duration must be positive.");
        }
        long seconds = duration.getSeconds();
        if (seconds <= 0L) {
            throw new IllegalArgumentException("Expiration duration must be at least one second.");
        }
        return validateExpirationSeconds(seconds);
    }
}

package com.rismr1.mailboxgui.api.request;

import com.rismr1.mailboxgui.api.type.RecipientPolicy;
import com.rismr1.mailboxgui.api.type.CodReturnDestination;
import com.rismr1.mailboxgui.api.type.NetworkDeliveryTarget;
import org.bukkit.inventory.ItemStack;

import java.time.Duration;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

public final class PackageMailRequest {

    private final List<MailboxApiRecipient> recipients;
    private final String fromDisplayName;
    private final String message;
    private final UUID senderUuid;
    private final List<ItemStack> contents;
    private final int experienceAmount;
    private final double codAmount;
    private final List<ItemStack> codItemCurrencyContents;
    private final boolean returnCodPaymentToSender;
    private final CodReturnDestination codReturnDestination;
    private final boolean returnCodPaymentToAdminInbox;
    private final boolean returnDeclinedOrExpiredToAdminInbox;
    private final int deliveryDelaySeconds;
    private final boolean notifyRecipients;
    private final RecipientPolicy recipientPolicy;
    private final String sourcePluginName;
    private final long expirationDurationSeconds;
    private final NetworkDeliveryTarget networkDeliveryTarget;

    private PackageMailRequest(Builder builder) {
        this.recipients = Collections.unmodifiableList(new ArrayList<>(builder.recipients));
        this.fromDisplayName = normalize(builder.fromDisplayName);
        this.message = normalizeMessage(builder.message);
        this.senderUuid = builder.senderUuid;
        this.contents = Collections.unmodifiableList(cloneContents(builder.contents));
        this.experienceAmount = builder.experienceAmount;
        this.codAmount = builder.codAmount;
        this.codItemCurrencyContents = Collections.unmodifiableList(cloneContents(builder.codItemCurrencyContents));
        this.codReturnDestination = builder.codReturnDestination;
        this.returnCodPaymentToSender = this.codReturnDestination == CodReturnDestination.SENDER;
        this.returnCodPaymentToAdminInbox = builder.returnCodPaymentToAdminInbox;
        this.returnDeclinedOrExpiredToAdminInbox = builder.returnDeclinedOrExpiredToAdminInbox;
        this.deliveryDelaySeconds = builder.deliveryDelaySeconds;
        this.notifyRecipients = builder.notifyRecipients;
        this.recipientPolicy = builder.recipientPolicy;
        this.sourcePluginName = normalize(builder.sourcePluginName);
        this.expirationDurationSeconds = builder.expirationDurationSeconds;
        this.networkDeliveryTarget = builder.networkDeliveryTarget == null ? NetworkDeliveryTarget.wholeNetwork() : builder.networkDeliveryTarget;
    }

    public static Builder builder() {
        return new Builder();
    }

    public List<MailboxApiRecipient> getRecipients() {
        return recipients;
    }

    public String getFromDisplayName() {
        return fromDisplayName;
    }

    public String getMessage() {
        return message;
    }

    public UUID getSenderUuid() {
        return senderUuid;
    }

    public List<ItemStack> getContents() {
        return cloneContents(contents);
    }

    public int getExperienceAmount() {
        return experienceAmount;
    }

    public double getCodAmount() {
        return codAmount;
    }

    public List<ItemStack> getCodItemCurrencyContents() {
        return cloneContents(codItemCurrencyContents);
    }

    public boolean hasCodItemCurrencyContents() {
        return !codItemCurrencyContents.isEmpty();
    }

    public boolean hasCodPrice() {
        return codAmount > 0.0D || !codItemCurrencyContents.isEmpty();
    }

    public boolean isReturnCodPaymentToSender() {
        return returnCodPaymentToSender;
    }

    /**
     * Typed COD return destination. The legacy return-to-sender boolean maps to SENDER or NONE.
     */
    public CodReturnDestination getCodReturnDestination() {
        return codReturnDestination;
    }

    public boolean isReturnCodPaymentToAdminInbox() {
        return returnCodPaymentToAdminInbox;
    }

    public boolean isReturnDeclinedOrExpiredToAdminInbox() {
        return returnDeclinedOrExpiredToAdminInbox;
    }

    public int getDeliveryDelaySeconds() {
        return deliveryDelaySeconds;
    }

    public boolean isNotifyRecipients() {
        return notifyRecipients;
    }

    public RecipientPolicy getRecipientPolicy() {
        return recipientPolicy;
    }

    public String getSourcePluginName() {
        return sourcePluginName;
    }

    /**
     * Requested expiration duration in seconds. Zero means non-expiring; delayed mail starts this duration at actual delivery.
     */
    public long getExpirationDurationSeconds() {
        return expirationDurationSeconds;
    }

    public boolean hasExpiration() {
        return expirationDurationSeconds > 0L;
    }

    public NetworkDeliveryTarget getNetworkDeliveryTarget() {
        return networkDeliveryTarget;
    }

    private static List<ItemStack> cloneContents(List<ItemStack> source) {
        List<ItemStack> cloned = new ArrayList<>();
        if (source == null) {
            return cloned;
        }

        for (ItemStack item : source) {
            if (item == null || item.getType().isAir()) {
                continue;
            }

            cloned.add(item.clone());
        }
        return cloned;
    }

    private static String normalize(String input) {
        if (input == null) {
            return null;
        }
        String trimmed = input.trim();
        return trimmed.isEmpty() ? null : trimmed;
    }

    public static final class Builder {
        private final List<MailboxApiRecipient> recipients = new ArrayList<>();
        private final List<ItemStack> contents = new ArrayList<>();
        private final List<ItemStack> codItemCurrencyContents = new ArrayList<>();
        private String fromDisplayName;
        private String message;
        private UUID senderUuid;
        private int experienceAmount;
        private double codAmount;
        private CodReturnDestination codReturnDestination = CodReturnDestination.NONE;
        private boolean returnCodPaymentToAdminInbox;
        private boolean returnDeclinedOrExpiredToAdminInbox;
        private int deliveryDelaySeconds = -1;
        private boolean notifyRecipients = true;
        private RecipientPolicy recipientPolicy = RecipientPolicy.KNOWN_MAILBOXGUI_PLAYER;
        private String sourcePluginName;
        private long expirationDurationSeconds;
        private NetworkDeliveryTarget networkDeliveryTarget = NetworkDeliveryTarget.wholeNetwork();

        public Builder recipient(UUID uuid, String name) {
            this.recipients.add(MailboxApiRecipient.of(uuid, name));
            return this;
        }

        public Builder recipient(UUID uuid) {
            this.recipients.add(MailboxApiRecipient.uuid(uuid));
            return this;
        }

        public Builder recipient(String name) {
            this.recipients.add(MailboxApiRecipient.name(name));
            return this;
        }

        public Builder recipients(List<MailboxApiRecipient> recipients) {
            if (recipients != null) {
                this.recipients.addAll(recipients);
            }
            return this;
        }

        public Builder fromDisplayName(String fromDisplayName) {
            this.fromDisplayName = fromDisplayName;
            return this;
        }

        public Builder message(String message) {
            this.message = normalizeMessage(message);
            return this;
        }

        public Builder senderUuid(UUID senderUuid) {
            this.senderUuid = senderUuid;
            return this;
        }

        public Builder addItem(ItemStack item) {
            if (item != null && !item.getType().isAir()) {
                this.contents.add(item.clone());
            }
            return this;
        }

        public Builder contents(List<ItemStack> contents) {
            this.contents.clear();
            this.contents.addAll(cloneContents(contents));
            return this;
        }

        public Builder experienceAmount(int experienceAmount) {
            this.experienceAmount = Math.max(0, experienceAmount);
            return this;
        }

        public Builder codAmount(double codAmount) {
            this.codAmount = Math.max(0.0D, codAmount);
            return this;
        }

        public Builder addCodItemCurrency(ItemStack item) {
            if (item != null && !item.getType().isAir()) {
                this.codItemCurrencyContents.add(item.clone());
            }
            return this;
        }

        public Builder codItemCurrencyContents(List<ItemStack> codItemCurrencyContents) {
            this.codItemCurrencyContents.clear();
            this.codItemCurrencyContents.addAll(cloneContents(codItemCurrencyContents));
            return this;
        }

        public Builder clearCodItemCurrencyContents() {
            this.codItemCurrencyContents.clear();
            return this;
        }

        public Builder returnCodPaymentToSender(boolean returnCodPaymentToSender) {
            this.codReturnDestination = returnCodPaymentToSender ? CodReturnDestination.SENDER : CodReturnDestination.NONE;
            return this;
        }

        public Builder codReturnDestination(CodReturnDestination destination) {
            this.codReturnDestination = destination == null ? CodReturnDestination.NONE : destination;
            return this;
        }

        public Builder returnCodPaymentToAdminInbox(boolean enabled) {
            this.returnCodPaymentToAdminInbox = enabled;
            return this;
        }

        public Builder returnDeclinedOrExpiredToAdminInbox(boolean enabled) {
            this.returnDeclinedOrExpiredToAdminInbox = enabled;
            return this;
        }

        public Builder deliveryDelaySeconds(int deliveryDelaySeconds) {
            this.deliveryDelaySeconds = deliveryDelaySeconds;
            return this;
        }

        public Builder notifyRecipients(boolean notifyRecipients) {
            this.notifyRecipients = notifyRecipients;
            return this;
        }

        public Builder recipientPolicy(RecipientPolicy recipientPolicy) {
            if (recipientPolicy != null) {
                this.recipientPolicy = recipientPolicy;
            }
            return this;
        }

        public Builder sourcePluginName(String sourcePluginName) {
            this.sourcePluginName = sourcePluginName;
            return this;
        }

        public Builder expirationDurationSeconds(long seconds) {
            this.expirationDurationSeconds = validateExpirationSeconds(seconds);
            return this;
        }

        public Builder expiresAfter(Duration duration) {
            this.expirationDurationSeconds = validateExpirationDuration(duration);
            return this;
        }

        public Builder networkDeliveryTarget(NetworkDeliveryTarget target) {
            this.networkDeliveryTarget = target == null ? NetworkDeliveryTarget.wholeNetwork() : target;
            return this;
        }

        public PackageMailRequest build() {
            return new PackageMailRequest(this);
        }
    }

    private static long validateExpirationSeconds(long seconds) {
        if (seconds < 0L) {
            throw new IllegalArgumentException("expirationDurationSeconds cannot be negative.");
        }
        Math.multiplyExact(seconds, 1000L);
        return seconds;
    }

    private static String normalizeMessage(String input) {
        String normalized = input == null || input.isBlank() ? null : input;
        if (normalized != null && !com.rismr1.mailboxgui.api.message.MailMessageRules.isValid(normalized)) {
            throw new IllegalArgumentException("Package message requires at most 256 visible characters and 17 body lines total, including automatic wrapping and /n.");
        }
        return normalized;
    }

    private static long validateExpirationDuration(Duration duration) {
        if (duration == null || duration.isZero() || duration.isNegative()) {
            throw new IllegalArgumentException("Expiration duration must be positive.");
        }
        long seconds = duration.getSeconds();
        if (seconds <= 0L) {
            throw new IllegalArgumentException("Expiration duration must be at least one second.");
        }
        return validateExpirationSeconds(seconds);
    }
}

package com.rismr1.mailboxgui.api.request;

import com.rismr1.mailboxgui.api.type.RecipientPolicy;
import com.rismr1.mailboxgui.api.type.NetworkDeliveryTarget;

import java.time.Duration;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

public final class MoneyMailRequest {

    private final List<MailboxApiRecipient> recipients;
    private final String fromDisplayName;
    private final String message;
    private final double amount;
    private final int deliveryDelaySeconds;
    private final boolean notifyRecipients;
    private final RecipientPolicy recipientPolicy;
    private final String sourcePluginName;
    private final long expirationDurationSeconds;
    private final NetworkDeliveryTarget networkDeliveryTarget;

    private MoneyMailRequest(Builder builder) {
        this.recipients = Collections.unmodifiableList(new ArrayList<>(builder.recipients));
        this.fromDisplayName = normalize(builder.fromDisplayName);
        this.message = normalizeMessage(builder.message);
        this.amount = builder.amount;
        this.deliveryDelaySeconds = builder.deliveryDelaySeconds;
        this.notifyRecipients = builder.notifyRecipients;
        this.recipientPolicy = builder.recipientPolicy;
        this.sourcePluginName = normalize(builder.sourcePluginName);
        this.expirationDurationSeconds = builder.expirationDurationSeconds;
        this.networkDeliveryTarget = builder.networkDeliveryTarget == null ? NetworkDeliveryTarget.wholeNetwork() : builder.networkDeliveryTarget;
    }

    public static Builder builder() {
        return new Builder();
    }

    public List<MailboxApiRecipient> getRecipients() {
        return recipients;
    }

    public String getFromDisplayName() {
        return fromDisplayName;
    }

    public String getMessage() {
        return message;
    }

    public double getAmount() {
        return amount;
    }

    public int getDeliveryDelaySeconds() {
        return deliveryDelaySeconds;
    }

    public boolean isNotifyRecipients() {
        return notifyRecipients;
    }

    public RecipientPolicy getRecipientPolicy() {
        return recipientPolicy;
    }

    public String getSourcePluginName() {
        return sourcePluginName;
    }

    /**
     * Requested expiration duration in seconds. Zero means non-expiring; delayed mail starts this duration at actual delivery.
     */
    public long getExpirationDurationSeconds() {
        return expirationDurationSeconds;
    }

    public boolean hasExpiration() {
        return expirationDurationSeconds > 0L;
    }

    public NetworkDeliveryTarget getNetworkDeliveryTarget() {
        return networkDeliveryTarget;
    }

    private static String normalize(String input) {
        if (input == null) {
            return null;
        }
        String trimmed = input.trim();
        return trimmed.isEmpty() ? null : trimmed;
    }

    public static final class Builder {
        private final List<MailboxApiRecipient> recipients = new ArrayList<>();
        private String fromDisplayName;
        private String message;
        private double amount;
        private int deliveryDelaySeconds = -1;
        private boolean notifyRecipients = true;
        private RecipientPolicy recipientPolicy = RecipientPolicy.KNOWN_MAILBOXGUI_PLAYER;
        private String sourcePluginName;
        private long expirationDurationSeconds;
        private NetworkDeliveryTarget networkDeliveryTarget = NetworkDeliveryTarget.wholeNetwork();

        public Builder recipient(UUID uuid, String name) {
            this.recipients.add(MailboxApiRecipient.of(uuid, name));
            return this;
        }

        public Builder recipient(UUID uuid) {
            this.recipients.add(MailboxApiRecipient.uuid(uuid));
            return this;
        }

        public Builder recipient(String name) {
            this.recipients.add(MailboxApiRecipient.name(name));
            return this;
        }

        public Builder recipients(List<MailboxApiRecipient> recipients) {
            if (recipients != null) {
                this.recipients.addAll(recipients);
            }
            return this;
        }

        public Builder fromDisplayName(String fromDisplayName) {
            this.fromDisplayName = fromDisplayName;
            return this;
        }

        public Builder message(String message) {
            this.message = normalizeMessage(message);
            return this;
        }

        public Builder amount(double amount) {
            this.amount = amount;
            return this;
        }

        public Builder deliveryDelaySeconds(int deliveryDelaySeconds) {
            this.deliveryDelaySeconds = deliveryDelaySeconds;
            return this;
        }

        public Builder notifyRecipients(boolean notifyRecipients) {
            this.notifyRecipients = notifyRecipients;
            return this;
        }

        public Builder recipientPolicy(RecipientPolicy recipientPolicy) {
            if (recipientPolicy != null) {
                this.recipientPolicy = recipientPolicy;
            }
            return this;
        }

        public Builder sourcePluginName(String sourcePluginName) {
            this.sourcePluginName = sourcePluginName;
            return this;
        }

        public Builder expirationDurationSeconds(long seconds) {
            this.expirationDurationSeconds = validateExpirationSeconds(seconds);
            return this;
        }

        public Builder expiresAfter(Duration duration) {
            this.expirationDurationSeconds = validateExpirationDuration(duration);
            return this;
        }

        public Builder networkDeliveryTarget(NetworkDeliveryTarget target) {
            this.networkDeliveryTarget = target == null ? NetworkDeliveryTarget.wholeNetwork() : target;
            return this;
        }

        public MoneyMailRequest build() {
            return new MoneyMailRequest(this);
        }
    }

    private static long validateExpirationSeconds(long seconds) {
        if (seconds < 0L) {
            throw new IllegalArgumentException("expirationDurationSeconds cannot be negative.");
        }
        Math.multiplyExact(seconds, 1000L);
        return seconds;
    }

    private static String normalizeMessage(String input) {
        String normalized = input == null || input.isBlank() ? null : input;
        if (normalized != null && !com.rismr1.mailboxgui.api.message.MailMessageRules.isValid(normalized)) {
            throw new IllegalArgumentException("Money mail message requires at most 256 visible characters and 17 body lines total, including automatic wrapping and /n.");
        }
        return normalized;
    }

    private static long validateExpirationDuration(Duration duration) {
        if (duration == null || duration.isZero() || duration.isNegative()) {
            throw new IllegalArgumentException("Expiration duration must be positive.");
        }
        long seconds = duration.getSeconds();
        if (seconds <= 0L) {
            throw new IllegalArgumentException("Expiration duration must be at least one second.");
        }
        return validateExpirationSeconds(seconds);
    }
}

package com.rismr1.mailboxgui.api.result;

import com.rismr1.mailboxgui.api.type.MailType;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;

public final class MailboxSendResult {

    private final MailType mailType;
    private final List<MailboxRecipientResult> recipientResults;
    private final List<String> warnings;

    public MailboxSendResult(MailType mailType, List<MailboxRecipientResult> recipientResults, List<String> warnings) {
        this.mailType = mailType;
        this.recipientResults = Collections.unmodifiableList(new ArrayList<>(recipientResults == null ? List.of() : recipientResults));
        this.warnings = Collections.unmodifiableList(new ArrayList<>(warnings == null ? List.of() : warnings));
    }

    public static MailboxSendResult singleFailure(MailType mailType, RecipientStatus status, String message) {
        return new MailboxSendResult(
                mailType,
                List.of(new MailboxRecipientResult(null, null, status, message)),
                List.of()
        );
    }

    public MailType getMailType() {
        return mailType;
    }

    public List<MailboxRecipientResult> getRecipientResults() {
        return recipientResults;
    }

    public List<String> getWarnings() {
        return warnings;
    }

    public boolean isSuccessful() {
        return !recipientResults.isEmpty() && recipientResults.stream().allMatch(MailboxRecipientResult::isSuccessful);
    }

    public int getRequestedRecipients() {
        return recipientResults.size();
    }

    public int getDeliveredRecipients() {
        return (int) recipientResults.stream().filter(result -> result.getStatus() == RecipientStatus.DELIVERED).count();
    }

    public int getQueuedRecipients() {
        return (int) recipientResults.stream().filter(result -> result.getStatus() == RecipientStatus.QUEUED).count();
    }

    public int getFailedRecipients() {
        return (int) recipientResults.stream().filter(result -> !result.isSuccessful()).count();
    }

    public List<String> getDeliveredMailIds() {
        List<String> ids = new ArrayList<>();
        for (MailboxRecipientResult result : recipientResults) {
            if (result != null && result.hasMailId()) {
                ids.add(result.getMailId());
            }
        }
        return Collections.unmodifiableList(ids);
    }

    public List<String> getQueuedDeliveryIds() {
        List<String> ids = new ArrayList<>();
        for (MailboxRecipientResult result : recipientResults) {
            if (result != null && result.hasQueueId()) {
                ids.add(result.getQueueId());
            }
        }
        return Collections.unmodifiableList(ids);
    }

    public boolean hasExpiringDeliveries() {
        return recipientResults.stream().anyMatch(MailboxRecipientResult::hasExpiration);
    }

    public Map<UUID, String> getSuccessfulRecipientMailIds() {
        Map<UUID, String> ids = new LinkedHashMap<>();
        for (MailboxRecipientResult result : recipientResults) {
            if (result != null && result.getRecipientUuid() != null && result.hasMailId()) {
                ids.put(result.getRecipientUuid(), result.getMailId());
            }
        }
        return Collections.unmodifiableMap(ids);
    }
}

package com.rismr1.mailboxgui.api.result;

import java.util.UUID;

public final class MailboxRecipientResult {

    private final UUID recipientUuid;
    private final String recipientName;
    private final RecipientStatus status;
    private final String message;
    private final String mailId;
    private final long expirationTimestampMillis;
    private final String queueId;
    private final long expirationDurationSeconds;

    public MailboxRecipientResult(UUID recipientUuid, String recipientName, RecipientStatus status, String message) {
        this(recipientUuid, recipientName, status, message, null, 0L, null, 0L);
    }

    public MailboxRecipientResult(UUID recipientUuid,
                                  String recipientName,
                                  RecipientStatus status,
                                  String message,
                                  String mailId,
                                  long expirationTimestampMillis,
                                  String queueId,
                                  long expirationDurationSeconds) {
        this.recipientUuid = recipientUuid;
        this.recipientName = recipientName;
        this.status = status == null ? RecipientStatus.INVALID_REQUEST : status;
        this.message = message == null ? "" : message;
        this.mailId = normalize(mailId);
        this.expirationTimestampMillis = Math.max(0L, expirationTimestampMillis);
        this.queueId = normalize(queueId);
        this.expirationDurationSeconds = Math.max(0L, expirationDurationSeconds);
    }

    public UUID getRecipientUuid() {
        return recipientUuid;
    }

    public String getRecipientName() {
        return recipientName;
    }

    public RecipientStatus getStatus() {
        return status;
    }

    public String getMessage() {
        return message;
    }

    /**
     * Actual stored permanent mail ID for immediate successful deliveries.
     */
    public String getMailId() {
        return mailId;
    }

    public boolean hasMailId() {
        return mailId != null;
    }

    /**
     * Final absolute expiration timestamp for immediate delivery, or zero for non-expiring/queued results.
     */
    public long getExpirationTimestampMillis() {
        return expirationTimestampMillis;
    }

    public boolean hasExpiration() {
        return expirationTimestampMillis > 0L || expirationDurationSeconds > 0L;
    }

    /**
     * Delayed queue ID for queued deliveries.
     */
    public String getQueueId() {
        return queueId;
    }

    public boolean hasQueueId() {
        return queueId != null;
    }

    /**
     * Requested expiration duration for queued delivery; final timestamp is calculated at delivery time.
     */
    public long getExpirationDurationSeconds() {
        return expirationDurationSeconds;
    }

    public boolean isSuccessful() {
        return status == RecipientStatus.DELIVERED || status == RecipientStatus.QUEUED;
    }

    private static String normalize(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }
        return value.trim();
    }
}

package com.rismr1.mailboxgui.api.result;

public enum RecipientStatus {
    DELIVERED,
    QUEUED,
    RECIPIENT_NOT_FOUND,
    NO_REGISTERED_MAILBOX,
    MAILBOX_DATA_MISSING,
    INVALID_REQUEST,
    CANCELLED_BY_EVENT,
    INBOX_WRITE_FAILED,
    DISABLED_BY_CONFIG,
    ECONOMY_UNAVAILABLE,
    TOO_MANY_CONTENTS,
    EMPTY_PACKAGE,
    INVALID_EXPIRATION,
    ADMIN_INBOX_DISABLED,
    INVALID_COD_RETURN_DESTINATION,
    INVALID_COD_RETURN_CONFIGURATION,
    NESTED_PACKAGE_BLOCKED,
    NON_EMPTY_SHULKER_BLOCKED,
    SERIALIZATION_FAILED,
    NETWORK_MODE_REQUIRED,
    UNKNOWN_BACKEND,
    UNKNOWN_BACKEND_GROUP,
    NO_COMPATIBLE_BACKEND,
    BACKEND_TARGET_BLOCKED,
    ITEM_UNSUPPORTED_ON_TARGET_BACKEND,
    COD_PAYMENT_UNSUPPORTED_ON_TARGET_BACKEND,
    MAIL_RESTRICTED_TO_OTHER_BACKEND
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.ApiCapability;

import java.util.Set;

public record MailboxApiInfo(
        String apiVersion,
        String pluginVersion,
        String edition,
        boolean primaryThreadRequired,
        int packageContentLimit,
        Set<ApiCapability> capabilities
) {
    public MailboxApiInfo {
        apiVersion = apiVersion == null ? "unknown" : apiVersion;
        pluginVersion = pluginVersion == null ? "unknown" : pluginVersion;
        edition = edition == null ? "unknown" : edition;
        capabilities = capabilities == null ? Set.of() : Set.copyOf(capabilities);
    }

    public boolean supports(ApiCapability capability) {
        return capability != null && capabilities.contains(capability);
    }
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.MailType;

import java.util.Set;

public record InboxQuery(
        int page,
        int pageSize,
        Set<MailType> mailTypes,
        boolean includeQueued,
        boolean includeExpired,
        SortOrder sortOrder
) {
    public InboxQuery {
        page = Math.max(0, page);
        pageSize = Math.max(1, Math.min(100, pageSize));
        mailTypes = mailTypes == null ? Set.of() : Set.copyOf(mailTypes);
        sortOrder = sortOrder == null ? SortOrder.NEWEST_FIRST : sortOrder;
    }

    public static InboxQuery firstPage() {
        return new InboxQuery(0, 36, Set.of(), true, true, SortOrder.NEWEST_FIRST);
    }

    public enum SortOrder {
        NEWEST_FIRST,
        OLDEST_FIRST,
        TYPE_THEN_NEWEST,
        EXPIRING_FIRST
    }
}

package com.rismr1.mailboxgui.api.model;

import java.util.List;
import java.util.UUID;

public record InboxPage(UUID ownerUuid, int page, int pageSize, int totalEntries, int totalPages, List<InboxMailEntry> entries) {
    public InboxPage {
        entries = entries == null ? List.of() : List.copyOf(entries);
    }
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.MailLifecycleStatus;
import com.rismr1.mailboxgui.api.type.MailType;
import org.bukkit.inventory.ItemStack;

public record InboxMailEntry(
        String mailId,
        MailType mailType,
        MailLifecycleStatus status,
        String senderName,
        long sentAtMillis,
        long expiresAtMillis,
        boolean unchecked,
        boolean queued,
        int packageContentCount,
        double moneyAmount,
        String attachedMessage,
        String originBackendId,
        long revision,
        ItemStack snapshot
) {
    public InboxMailEntry {
        senderName = senderName == null ? "" : senderName;
        attachedMessage = attachedMessage == null ? "" : attachedMessage;
        originBackendId = originBackendId == null ? "" : originBackendId;
        snapshot = snapshot == null ? null : snapshot.clone();
    }

    @Override
    public ItemStack snapshot() {
        return snapshot == null ? null : snapshot.clone();
    }
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.ApiOperationStatus;
import com.rismr1.mailboxgui.api.type.MailType;

public record MailMutationResult(ApiOperationStatus status, String mailId, MailType mailType, long revision, int remainingMail, String message) {
    public MailMutationResult {
        status = status == null ? ApiOperationStatus.INTERNAL_ERROR : status;
        message = message == null ? "" : message;
    }

    public boolean successful() {
        return status == ApiOperationStatus.SUCCESS;
    }
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.MailDeliveryType;

import java.util.UUID;

public record DelayedMailEntry(String queueId, UUID recipientUuid, String recipientName, MailDeliveryType mailType,
                               long createdAtMillis, long deliverAtMillis, long expirationDurationSeconds,
                               String originBackendId, boolean processableOnCurrentBackend) {
}

package com.rismr1.mailboxgui.api.model;

import java.util.Map;

public record ScheduledMailTask(String id, boolean enabled, String type, String from, boolean notifyRecipients,
                                long nextDueMillis, boolean valid, boolean completed, long lastRunMillis,
                                int lastDelivered, int lastQueued, int lastFailed, String lastFailure,
                                Map<String, Object> definition) {
    public ScheduledMailTask {
        definition = definition == null ? Map.of() : Map.copyOf(definition);
        lastFailure = lastFailure == null ? "" : lastFailure;
    }
}

package com.rismr1.mailboxgui.api.model;

import com.rismr1.mailboxgui.api.type.ApiOperationStatus;

public record ScheduledMailRunResult(ApiOperationStatus status, int recipients, int delivered, int queued, int failed, String message) {
    public boolean successful() {
        return status == ApiOperationStatus.SUCCESS;
    }
}

package com.rismr1.mailboxgui.api.model;

public record MailboxLocation(String world, int x, int y, int z, boolean loaded, String backendId) {
    public MailboxLocation {
        world = world == null ? "" : world;
        backendId = backendId == null ? "" : backendId;
    }
}

package com.rismr1.mailboxgui.api.model;

import java.util.UUID;

public record RegisteredMailbox(UUID ownerUuid, String ownerName, int mailboxNumber, MailboxLocation container, MailboxLocation sign) {
}

package com.rismr1.mailboxgui.api.model;

public record PublicMailbox(String id, String name, MailboxLocation container, MailboxLocation sign) {
}

package com.rismr1.mailboxgui.api.model;

public record PublicAccessNpc(String id, String name, MailboxLocation location) {
}

package com.rismr1.mailboxgui.api.type;

public enum ApiCapability {
    INBOX_QUERY,
    TRANSACTIONAL_MUTATION,
    DELIVERY_TRACKING,
    SCHEDULED_MAIL,
    MAILBOX_REGISTRY,
    CUSTOM_ITEM_CODECS,
    NOTIFICATION_PROVIDERS,
    LIFECYCLE_EVENTS,
    ATTACHED_MESSAGES,
    MESSAGE_VALIDATION,
    NETWORK_DELIVERY_TARGETS,
    VAULT_ECONOMY,
    ITEM_CURRENCY_COD,
    PACKAGE_EXPERIENCE,
    RESOURCE_PACK_STATUS
}

package com.rismr1.mailboxgui.api.type;

public enum ApiOperationStatus {
    SUCCESS,
    NOT_FOUND,
    ALREADY_COMPLETED,
    REVISION_CONFLICT,
    EXPIRED,
    INVALID_REQUEST,
    INVALID_MAIL_TYPE,
    BUSY,
    DISABLED,
    UNSUPPORTED,
    ECONOMY_UNAVAILABLE,
    INSUFFICIENT_FUNDS,
    INBOX_FULL,
    UNSUPPORTED_ITEM,
    BACKEND_RESTRICTED,
    STORAGE_FAILURE,
    INVENTORY_FAILURE,
    CANCELLED_BY_EVENT,
    INTERNAL_ERROR
}

package com.rismr1.mailboxgui.api.type;

public enum RecipientPolicy {
    REGISTERED_MAILBOX_ONLY,
    KNOWN_MAILBOXGUI_PLAYER,
    CREATE_IF_MISSING
}

package com.rismr1.mailboxgui.api.type;

/**
 * Destination for API-created COD package return handling.
 */
public enum CodReturnDestination {
    /**
     * No explicit COD return destination.
     */
    NONE,
    /**
     * Return COD payments or eligible package contents to the request sender.
     */
    SENDER,
    /**
     * Preserve COD return handling for the Shared Admin Inbox.
     */
    ADMIN_INBOX
}

package com.rismr1.mailboxgui.api.type;

public enum MailType {
    LETTER,
    PACKAGE,
    MONEY
}

package com.rismr1.mailboxgui.api.type;

public enum MailDeliveryType {
    LETTER,
    BOOK_LETTER,
    PACKAGE,
    COD_PACKAGE,
    RETURNED_COD_PACKAGE,
    COD_ITEM_CURRENCY_PAYMENT,
    MONEY_MAIL
}

package com.rismr1.mailboxgui.api.type;

public enum MailLifecycleStatus {
    QUEUED,
    DELIVERED,
    VIEWED,
    CLAIMED,
    DELETED,
    EXPIRED,
    RETURNED,
    CANCELLED,
    FAILED
}

package com.rismr1.mailboxgui.api.type;

public enum MailDeliverySource {
    LOCAL_DELIVERY,
    PLAYER_ACTION,
    ADMIN_COMMAND,
    API,
    DELAYED_QUEUE,
    NETWORK_SYNC,
    SYSTEM
}

package com.rismr1.mailboxgui.api.type;

public enum MailDeliveryScope {
    SINGLE_SERVER,
    NETWORK
}

package com.rismr1.mailboxgui.api.type;

public enum MailDeliveryOrigin {
    PLAYER,
    ADMIN,
    API,
    SYSTEM
}

package com.rismr1.mailboxgui.api.type;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Locale;

public final class NetworkDeliveryTarget {

    public enum Type {
        WHOLE_NETWORK,
        CURRENT_BACKEND_ONLY,
        ONLY_BACKENDS,
        EXCLUDE_BACKENDS,
        BACKEND_GROUP
    }

    private static final NetworkDeliveryTarget WHOLE_NETWORK = new NetworkDeliveryTarget(Type.WHOLE_NETWORK, List.of(), List.of(), null);
    private static final NetworkDeliveryTarget CURRENT_BACKEND_ONLY = new NetworkDeliveryTarget(Type.CURRENT_BACKEND_ONLY, List.of(), List.of(), null);

    private final Type type;
    private final List<String> allowedBackends;
    private final List<String> excludedBackends;
    private final String backendGroup;

    private NetworkDeliveryTarget(Type type, List<String> allowedBackends, List<String> excludedBackends, String backendGroup) {
        this.type = type == null ? Type.WHOLE_NETWORK : type;
        this.allowedBackends = Collections.unmodifiableList(normalizeList(allowedBackends));
        this.excludedBackends = Collections.unmodifiableList(normalizeList(excludedBackends));
        this.backendGroup = normalizeToken(backendGroup);
    }

    public static NetworkDeliveryTarget wholeNetwork() {
        return WHOLE_NETWORK;
    }

    public static NetworkDeliveryTarget currentBackendOnly() {
        return CURRENT_BACKEND_ONLY;
    }

    public static NetworkDeliveryTarget onlyBackends(List<String> backendIds) {
        return new NetworkDeliveryTarget(Type.ONLY_BACKENDS, backendIds, List.of(), null);
    }

    public static NetworkDeliveryTarget excludeBackends(List<String> backendIds) {
        return new NetworkDeliveryTarget(Type.EXCLUDE_BACKENDS, List.of(), backendIds, null);
    }

    public static NetworkDeliveryTarget backendGroup(String groupName) {
        return new NetworkDeliveryTarget(Type.BACKEND_GROUP, List.of(), List.of(), groupName);
    }

    public Type getType() {
        return type;
    }

    public List<String> getAllowedBackends() {
        return allowedBackends;
    }

    public List<String> getExcludedBackends() {
        return excludedBackends;
    }

    public String getBackendGroup() {
        return backendGroup;
    }

    public boolean isWholeNetwork() {
        return type == Type.WHOLE_NETWORK;
    }

    private static List<String> normalizeList(List<String> values) {
        List<String> normalized = new ArrayList<>();
        if (values == null) {
            return normalized;
        }

        for (String value : values) {
            String token = normalizeToken(value);
            if (token != null && !normalized.contains(token)) {
                normalized.add(token);
            }
        }
        return normalized;
    }

    private static String normalizeToken(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }

        return value.trim().toLowerCase(Locale.ROOT);
    }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.request.MailboxApiRecipient;
import com.rismr1.mailboxgui.api.type.MailType;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.List;

public final class MailboxMailPreSendEvent extends Event implements Cancellable {
    private static final HandlerList HANDLERS = new HandlerList();

    private final MailType mailType;
    private final List<MailboxApiRecipient> recipients;
    private final String sourcePluginName;
    private boolean cancelled;

    public MailboxMailPreSendEvent(MailType mailType, List<MailboxApiRecipient> recipients, String sourcePluginName) {
        this.mailType = mailType;
        this.recipients = recipients == null ? List.of() : List.copyOf(recipients);
        this.sourcePluginName = sourcePluginName == null ? "Unknown" : sourcePluginName;
    }

    public MailType getMailType() { return mailType; }
    public List<MailboxApiRecipient> getRecipients() { return recipients; }
    public String getSourcePluginName() { return sourcePluginName; }
    @Override public boolean isCancelled() { return cancelled; }
    @Override public void setCancelled(boolean cancelled) { this.cancelled = cancelled; }
    @Override public HandlerList getHandlers() { return HANDLERS; }
    public static HandlerList getHandlerList() { return HANDLERS; }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.type.MailDeliveryOrigin;
import com.rismr1.mailboxgui.api.type.MailDeliveryScope;
import com.rismr1.mailboxgui.api.type.MailDeliverySource;
import com.rismr1.mailboxgui.api.type.MailDeliveryType;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.UUID;

public class MailboxMailDeliveredEvent extends Event {

    private static final HandlerList HANDLERS = new HandlerList();

    private final UUID recipientUuid;
    private final String recipientName;
    private final UUID senderUuid;
    private final String senderName;
    private final MailDeliveryOrigin origin;
    private final MailDeliveryType deliveryType;
    private final double codPrice;
    private final String codPriceText;
    private final double moneyAmount;
    private final boolean delayedDelivery;
    private final boolean partOfMassDelivery;

    private final String eventId;
    private final String mailId;
    private final String originServerId;
    private final String originServerDisplayName;
    private final String currentServerId;
    private final String currentServerDisplayName;
    private final boolean networkMode;
    private final boolean localOrigin;
    private final boolean syncOrigin;
    private final MailDeliveryScope deliveryScope;
    private final MailDeliverySource deliverySource;
    private final long expirationTimestampMillis;
    private final String attachedMessage;

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery
    ) {
        this(
                recipientUuid,
                recipientName,
                senderUuid,
                senderName,
                origin,
                deliveryType,
                codPrice,
                null,
                moneyAmount,
                delayedDelivery,
                partOfMassDelivery
        );
    }

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery
    ) {
        this(
                recipientUuid,
                recipientName,
                senderUuid,
                senderName,
                origin,
                deliveryType,
                codPrice,
                codPriceText,
                moneyAmount,
                delayedDelivery,
                partOfMassDelivery,
                UUID.randomUUID().toString(),
                null,
                "",
                "",
                "",
                "",
                false,
                true,
                false,
                MailDeliveryScope.SINGLE_SERVER,
                delayedDelivery ? MailDeliverySource.DELAYED_QUEUE : MailDeliverySource.LOCAL_DELIVERY,
                0L
        );
    }

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery,
            String eventId,
            String mailId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource
    ) {
        this(
                recipientUuid,
                recipientName,
                senderUuid,
                senderName,
                origin,
                deliveryType,
                codPrice,
                null,
                moneyAmount,
                delayedDelivery,
                partOfMassDelivery,
                eventId,
                mailId,
                originServerId,
                originServerDisplayName,
                currentServerId,
                currentServerDisplayName,
                networkMode,
                localOrigin,
                syncOrigin,
                deliveryScope,
                deliverySource,
                0L
        );
    }

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery,
            String eventId,
            String mailId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource
    ) {
        this.recipientUuid = recipientUuid;
        this.recipientName = sanitizeName(recipientName, "Unknown");
        this.senderUuid = senderUuid;
        this.senderName = sanitizeName(senderName, "Server");
        this.origin = origin != null ? origin : MailDeliveryOrigin.SYSTEM;
        this.deliveryType = deliveryType != null ? deliveryType : MailDeliveryType.PACKAGE;
        this.codPrice = sanitizeAmount(codPrice);
        this.codPriceText = sanitizeCodPriceText(codPriceText, this.codPrice);
        this.moneyAmount = sanitizeAmount(moneyAmount);
        this.delayedDelivery = delayedDelivery;
        this.partOfMassDelivery = partOfMassDelivery;

        this.eventId = sanitizeId(eventId);
        this.mailId = sanitizeNullableId(mailId);
        this.originServerId = sanitizeNullableText(originServerId);
        this.originServerDisplayName = sanitizeNullableText(originServerDisplayName);
        this.currentServerId = sanitizeNullableText(currentServerId);
        this.currentServerDisplayName = sanitizeNullableText(currentServerDisplayName);
        this.networkMode = networkMode;
        this.localOrigin = localOrigin;
        this.syncOrigin = syncOrigin;
        this.deliveryScope = deliveryScope != null ? deliveryScope : MailDeliveryScope.SINGLE_SERVER;
        this.deliverySource = deliverySource != null ? deliverySource : MailDeliverySource.LOCAL_DELIVERY;
        this.expirationTimestampMillis = 0L;
        this.attachedMessage = "";
    }

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery,
            String eventId,
            String mailId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource,
            long expirationTimestampMillis
    ) {
        this(recipientUuid, recipientName, senderUuid, senderName, origin, deliveryType, codPrice, codPriceText, moneyAmount, delayedDelivery, partOfMassDelivery, eventId, mailId, originServerId, originServerDisplayName, currentServerId, currentServerDisplayName, networkMode, localOrigin, syncOrigin, deliveryScope, deliverySource, expirationTimestampMillis, "");
    }

    public MailboxMailDeliveredEvent(
            UUID recipientUuid,
            String recipientName,
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            boolean partOfMassDelivery,
            String eventId,
            String mailId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource,
            long expirationTimestampMillis,
            String attachedMessage
    ) {
        this.recipientUuid = recipientUuid;
        this.recipientName = sanitizeName(recipientName, "Unknown");
        this.senderUuid = senderUuid;
        this.senderName = sanitizeName(senderName, "Server");
        this.origin = origin != null ? origin : MailDeliveryOrigin.SYSTEM;
        this.deliveryType = deliveryType != null ? deliveryType : MailDeliveryType.PACKAGE;
        this.codPrice = sanitizeAmount(codPrice);
        this.codPriceText = sanitizeCodPriceText(codPriceText, this.codPrice);
        this.moneyAmount = sanitizeAmount(moneyAmount);
        this.delayedDelivery = delayedDelivery;
        this.partOfMassDelivery = partOfMassDelivery;

        this.eventId = sanitizeId(eventId);
        this.mailId = sanitizeNullableId(mailId);
        this.originServerId = sanitizeNullableText(originServerId);
        this.originServerDisplayName = sanitizeNullableText(originServerDisplayName);
        this.currentServerId = sanitizeNullableText(currentServerId);
        this.currentServerDisplayName = sanitizeNullableText(currentServerDisplayName);
        this.networkMode = networkMode;
        this.localOrigin = localOrigin;
        this.syncOrigin = syncOrigin;
        this.deliveryScope = deliveryScope != null ? deliveryScope : MailDeliveryScope.SINGLE_SERVER;
        this.deliverySource = deliverySource != null ? deliverySource : MailDeliverySource.LOCAL_DELIVERY;
        this.expirationTimestampMillis = Math.max(0L, expirationTimestampMillis);
        this.attachedMessage = attachedMessage == null ? "" : attachedMessage;
    }

    public UUID getRecipientUuid() {
        return recipientUuid;
    }

    /** Raw attached message, including /n syntax; empty when this mail has no attachment. */
    public String getAttachedMessage() { return attachedMessage; }

    public String getRecipientName() {
        return recipientName;
    }

    public UUID getSenderUuid() {
        return senderUuid;
    }

    public String getSenderName() {
        return senderName;
    }

    public MailDeliveryOrigin getOrigin() {
        return origin;
    }

    public MailDeliveryType getDeliveryType() {
        return deliveryType;
    }

    public double getCodPrice() {
        return codPrice;
    }

    public String getCodPriceText() {
        return codPriceText;
    }

    public double getMoneyAmount() {
        return moneyAmount;
    }

    public boolean isDelayedDelivery() {
        return delayedDelivery;
    }

    public boolean isPartOfMassDelivery() {
        return partOfMassDelivery;
    }

    public String getEventId() {
        return eventId;
    }

    public String getMailId() {
        return mailId;
    }

    public boolean hasMailId() {
        return mailId != null && !mailId.isBlank();
    }

    public String getOriginServerId() {
        return originServerId;
    }

    public String getOriginServerDisplayName() {
        return originServerDisplayName;
    }

    public String getCurrentServerId() {
        return currentServerId;
    }

    public String getCurrentServerDisplayName() {
        return currentServerDisplayName;
    }

    public boolean isNetworkMode() {
        return networkMode;
    }

    public boolean isLocalOrigin() {
        return localOrigin;
    }

    public boolean isSyncOrigin() {
        return syncOrigin;
    }

    public MailDeliveryScope getDeliveryScope() {
        return deliveryScope;
    }

    public MailDeliverySource getDeliverySource() {
        return deliverySource;
    }

    /**
     * Final absolute expiration timestamp stored on the delivered mail, or zero for non-expiring mail.
     */
    public long getExpirationTimestampMillis() {
        return expirationTimestampMillis;
    }

    public boolean hasExpiration() {
        return expirationTimestampMillis > 0L;
    }

    public boolean isAdminMail() {
        return origin == MailDeliveryOrigin.ADMIN;
    }

    public boolean isPlayerMail() {
        return origin == MailDeliveryOrigin.PLAYER;
    }

    public boolean isApiMail() {
        return origin == MailDeliveryOrigin.API;
    }

    public boolean hasSenderUuid() {
        return senderUuid != null;
    }

    public boolean hasCodPrice() {
        return codPrice > 0.0D || !codPriceText.isBlank();
    }

    public boolean hasCodPriceText() {
        return !codPriceText.isBlank();
    }

    public boolean hasMoneyAmount() {
        return moneyAmount > 0.0D;
    }

    @Override
    public HandlerList getHandlers() {
        return HANDLERS;
    }

    public static HandlerList getHandlerList() {
        return HANDLERS;
    }

    private static String sanitizeName(String value, String fallback) {
        if (value == null || value.isBlank()) {
            return fallback;
        }

        return value;
    }

    private static String sanitizeId(String value) {
        if (value == null || value.isBlank()) {
            return UUID.randomUUID().toString();
        }

        return value;
    }

    private static String sanitizeNullableId(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }

        return value;
    }

    private static String sanitizeNullableText(String value) {
        if (value == null) {
            return "";
        }

        return value;
    }

    private static String sanitizeCodPriceText(String value, double fallbackAmount) {
        if (value != null && !value.isBlank()) {
            return value.trim();
        }

        if (fallbackAmount > 0.0D) {
            return String.valueOf(fallbackAmount);
        }

        return "";
    }

    private static double sanitizeAmount(double value) {
        if (!Double.isFinite(value) || value < 0.0D) {
            return 0.0D;
        }

        return value;
    }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.type.MailDeliveryOrigin;
import com.rismr1.mailboxgui.api.type.MailDeliveryScope;
import com.rismr1.mailboxgui.api.type.MailDeliverySource;
import com.rismr1.mailboxgui.api.type.MailDeliveryType;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;

public class MailboxMassMailDeliveredEvent extends Event {

    private static final HandlerList HANDLERS = new HandlerList();

    private final UUID senderUuid;
    private final String senderName;
    private final MailDeliveryOrigin origin;
    private final MailDeliveryType deliveryType;
    private final int requestedRecipientCount;
    private final int successfulRecipientCount;
    private final int failedRecipientCount;
    private final double codPrice;
    private final String codPriceText;
    private final double moneyAmount;
    private final boolean delayedDelivery;
    private final List<UUID> successfulRecipientUuids;

    private final String eventId;
    private final String originServerId;
    private final String originServerDisplayName;
    private final String currentServerId;
    private final String currentServerDisplayName;
    private final boolean networkMode;
    private final boolean localOrigin;
    private final boolean syncOrigin;
    private final MailDeliveryScope deliveryScope;
    private final MailDeliverySource deliverySource;
    private final long expirationTimestampMillis;
    private final String attachedMessage;
    private final Map<UUID, String> successfulRecipientMailIds;

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids
    ) {
        this(
                senderUuid,
                senderName,
                origin,
                deliveryType,
                requestedRecipientCount,
                successfulRecipientCount,
                failedRecipientCount,
                codPrice,
                null,
                moneyAmount,
                delayedDelivery,
                successfulRecipientUuids
        );
    }

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids
    ) {
        this(
                senderUuid,
                senderName,
                origin,
                deliveryType,
                requestedRecipientCount,
                successfulRecipientCount,
                failedRecipientCount,
                codPrice,
                codPriceText,
                moneyAmount,
                delayedDelivery,
                successfulRecipientUuids,
                UUID.randomUUID().toString(),
                "",
                "",
                "",
                "",
                false,
                true,
                false,
                MailDeliveryScope.SINGLE_SERVER,
                delayedDelivery ? MailDeliverySource.DELAYED_QUEUE : MailDeliverySource.LOCAL_DELIVERY,
                0L,
                Map.of()
        );
    }

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids,
            String eventId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource
    ) {
        this(
                senderUuid,
                senderName,
                origin,
                deliveryType,
                requestedRecipientCount,
                successfulRecipientCount,
                failedRecipientCount,
                codPrice,
                null,
                moneyAmount,
                delayedDelivery,
                successfulRecipientUuids,
                eventId,
                originServerId,
                originServerDisplayName,
                currentServerId,
                currentServerDisplayName,
                networkMode,
                localOrigin,
                syncOrigin,
                deliveryScope,
                deliverySource,
                0L,
                Map.of()
        );
    }

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids,
            String eventId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource
    ) {
        this.senderUuid = senderUuid;
        this.senderName = sanitizeName(senderName, "Server");
        this.origin = origin != null ? origin : MailDeliveryOrigin.SYSTEM;
        this.deliveryType = deliveryType != null ? deliveryType : MailDeliveryType.PACKAGE;
        this.requestedRecipientCount = Math.max(0, requestedRecipientCount);
        this.successfulRecipientCount = Math.max(0, successfulRecipientCount);
        this.failedRecipientCount = Math.max(0, failedRecipientCount);
        this.codPrice = sanitizeAmount(codPrice);
        this.codPriceText = sanitizeCodPriceText(codPriceText, this.codPrice);
        this.moneyAmount = sanitizeAmount(moneyAmount);
        this.delayedDelivery = delayedDelivery;
        this.successfulRecipientUuids = successfulRecipientUuids == null
                ? Collections.emptyList()
                : List.copyOf(successfulRecipientUuids);

        this.eventId = sanitizeId(eventId);
        this.originServerId = sanitizeNullableText(originServerId);
        this.originServerDisplayName = sanitizeNullableText(originServerDisplayName);
        this.currentServerId = sanitizeNullableText(currentServerId);
        this.currentServerDisplayName = sanitizeNullableText(currentServerDisplayName);
        this.networkMode = networkMode;
        this.localOrigin = localOrigin;
        this.syncOrigin = syncOrigin;
        this.deliveryScope = deliveryScope != null ? deliveryScope : MailDeliveryScope.SINGLE_SERVER;
        this.deliverySource = deliverySource != null ? deliverySource : MailDeliverySource.LOCAL_DELIVERY;
        this.expirationTimestampMillis = 0L;
        this.attachedMessage = "";
        this.successfulRecipientMailIds = Collections.emptyMap();
    }

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids,
            String eventId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource,
            long expirationTimestampMillis,
            Map<UUID, String> successfulRecipientMailIds
    ) {
        this(senderUuid, senderName, origin, deliveryType, requestedRecipientCount, successfulRecipientCount, failedRecipientCount, codPrice, codPriceText, moneyAmount, delayedDelivery, successfulRecipientUuids, eventId, originServerId, originServerDisplayName, currentServerId, currentServerDisplayName, networkMode, localOrigin, syncOrigin, deliveryScope, deliverySource, expirationTimestampMillis, successfulRecipientMailIds, "");
    }

    public MailboxMassMailDeliveredEvent(
            UUID senderUuid,
            String senderName,
            MailDeliveryOrigin origin,
            MailDeliveryType deliveryType,
            int requestedRecipientCount,
            int successfulRecipientCount,
            int failedRecipientCount,
            double codPrice,
            String codPriceText,
            double moneyAmount,
            boolean delayedDelivery,
            List<UUID> successfulRecipientUuids,
            String eventId,
            String originServerId,
            String originServerDisplayName,
            String currentServerId,
            String currentServerDisplayName,
            boolean networkMode,
            boolean localOrigin,
            boolean syncOrigin,
            MailDeliveryScope deliveryScope,
            MailDeliverySource deliverySource,
            long expirationTimestampMillis,
            Map<UUID, String> successfulRecipientMailIds,
            String attachedMessage
    ) {
        this.senderUuid = senderUuid;
        this.senderName = sanitizeName(senderName, "Server");
        this.origin = origin != null ? origin : MailDeliveryOrigin.SYSTEM;
        this.deliveryType = deliveryType != null ? deliveryType : MailDeliveryType.PACKAGE;
        this.requestedRecipientCount = Math.max(0, requestedRecipientCount);
        this.successfulRecipientCount = Math.max(0, successfulRecipientCount);
        this.failedRecipientCount = Math.max(0, failedRecipientCount);
        this.codPrice = sanitizeAmount(codPrice);
        this.codPriceText = sanitizeCodPriceText(codPriceText, this.codPrice);
        this.moneyAmount = sanitizeAmount(moneyAmount);
        this.delayedDelivery = delayedDelivery;
        this.successfulRecipientUuids = successfulRecipientUuids == null
                ? Collections.emptyList()
                : List.copyOf(successfulRecipientUuids);

        this.eventId = sanitizeId(eventId);
        this.originServerId = sanitizeNullableText(originServerId);
        this.originServerDisplayName = sanitizeNullableText(originServerDisplayName);
        this.currentServerId = sanitizeNullableText(currentServerId);
        this.currentServerDisplayName = sanitizeNullableText(currentServerDisplayName);
        this.networkMode = networkMode;
        this.localOrigin = localOrigin;
        this.syncOrigin = syncOrigin;
        this.deliveryScope = deliveryScope != null ? deliveryScope : MailDeliveryScope.SINGLE_SERVER;
        this.deliverySource = deliverySource != null ? deliverySource : MailDeliverySource.LOCAL_DELIVERY;
        this.expirationTimestampMillis = Math.max(0L, expirationTimestampMillis);
        this.successfulRecipientMailIds = sanitizeMailIdMap(successfulRecipientMailIds);
        this.attachedMessage = attachedMessage == null ? "" : attachedMessage;
    }

    public UUID getSenderUuid() {
        return senderUuid;
    }

    /** Common raw attached message for this batch, or empty when there is no attachment. */
    public String getAttachedMessage() { return attachedMessage; }

    public String getSenderName() {
        return senderName;
    }

    public MailDeliveryOrigin getOrigin() {
        return origin;
    }

    public MailDeliveryType getDeliveryType() {
        return deliveryType;
    }

    public int getRequestedRecipientCount() {
        return requestedRecipientCount;
    }

    public int getSuccessfulRecipientCount() {
        return successfulRecipientCount;
    }

    public int getFailedRecipientCount() {
        return failedRecipientCount;
    }

    public double getCodPrice() {
        return codPrice;
    }

    public String getCodPriceText() {
        return codPriceText;
    }

    public double getMoneyAmount() {
        return moneyAmount;
    }

    public boolean isDelayedDelivery() {
        return delayedDelivery;
    }

    public List<UUID> getSuccessfulRecipientUuids() {
        return successfulRecipientUuids;
    }

    public String getEventId() {
        return eventId;
    }

    public String getOriginServerId() {
        return originServerId;
    }

    public String getOriginServerDisplayName() {
        return originServerDisplayName;
    }

    public String getCurrentServerId() {
        return currentServerId;
    }

    public String getCurrentServerDisplayName() {
        return currentServerDisplayName;
    }

    public boolean isNetworkMode() {
        return networkMode;
    }

    public boolean isLocalOrigin() {
        return localOrigin;
    }

    public boolean isSyncOrigin() {
        return syncOrigin;
    }

    public MailDeliveryScope getDeliveryScope() {
        return deliveryScope;
    }

    public MailDeliverySource getDeliverySource() {
        return deliverySource;
    }

    /**
     * Final absolute expiration timestamp shared by this delivery batch, or zero for non-expiring mail.
     */
    public long getExpirationTimestampMillis() {
        return expirationTimestampMillis;
    }

    public boolean hasExpiration() {
        return expirationTimestampMillis > 0L;
    }

    public Map<UUID, String> getSuccessfulRecipientMailIds() {
        return successfulRecipientMailIds;
    }

    public boolean isAdminMail() {
        return origin == MailDeliveryOrigin.ADMIN;
    }

    public boolean isApiMail() {
        return origin == MailDeliveryOrigin.API;
    }

    public boolean hasSenderUuid() {
        return senderUuid != null;
    }

    public boolean hasCodPrice() {
        return codPrice > 0.0D || !codPriceText.isBlank();
    }

    public boolean hasCodPriceText() {
        return !codPriceText.isBlank();
    }

    public boolean hasMoneyAmount() {
        return moneyAmount > 0.0D;
    }

    @Override
    public HandlerList getHandlers() {
        return HANDLERS;
    }

    public static HandlerList getHandlerList() {
        return HANDLERS;
    }

    private static String sanitizeName(String value, String fallback) {
        if (value == null || value.isBlank()) {
            return fallback;
        }

        return value;
    }

    private static String sanitizeId(String value) {
        if (value == null || value.isBlank()) {
            return UUID.randomUUID().toString();
        }

        return value;
    }

    private static String sanitizeNullableText(String value) {
        if (value == null) {
            return "";
        }

        return value;
    }

    private static String sanitizeCodPriceText(String value, double fallbackAmount) {
        if (value != null && !value.isBlank()) {
            return value.trim();
        }

        if (fallbackAmount > 0.0D) {
            return String.valueOf(fallbackAmount);
        }

        return "";
    }

    private static double sanitizeAmount(double value) {
        if (!Double.isFinite(value) || value < 0.0D) {
            return 0.0D;
        }

        return value;
    }

    private static Map<UUID, String> sanitizeMailIdMap(Map<UUID, String> source) {
        if (source == null || source.isEmpty()) {
            return Collections.emptyMap();
        }

        Map<UUID, String> sanitized = new LinkedHashMap<>();
        for (Map.Entry<UUID, String> entry : source.entrySet()) {
            if (entry.getKey() != null && entry.getValue() != null && !entry.getValue().isBlank()) {
                sanitized.put(entry.getKey(), entry.getValue().trim());
            }
        }
        return Collections.unmodifiableMap(sanitized);
    }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.type.MailType;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.UUID;

/**
 * Fired on the server thread before MailboxGUI changes or claims stored mail.
 * Cancelling this event prevents the mutation and any related payout or item transfer.
 */
public final class MailboxMailPreMutationEvent extends Event implements Cancellable {
    private static final HandlerList HANDLERS = new HandlerList();

    private final UUID ownerUuid;
    private final UUID actorUuid;
    private final String mailId;
    private final MailType mailType;
    private final Action action;
    private final String reason;
    private boolean cancelled;

    public MailboxMailPreMutationEvent(UUID ownerUuid, UUID actorUuid, String mailId, MailType mailType,
                                       Action action, String reason) {
        this.ownerUuid = ownerUuid;
        this.actorUuid = actorUuid;
        this.mailId = mailId == null ? "" : mailId;
        this.mailType = mailType;
        this.action = action;
        this.reason = reason == null ? "" : reason;
    }

    public UUID getOwnerUuid() { return ownerUuid; }
    public UUID getActorUuid() { return actorUuid; }
    public String getMailId() { return mailId; }
    public MailType getMailType() { return mailType; }
    public Action getAction() { return action; }
    public String getReason() { return reason; }
    @Override public boolean isCancelled() { return cancelled; }
    @Override public void setCancelled(boolean cancelled) { this.cancelled = cancelled; }
    @Override public HandlerList getHandlers() { return HANDLERS; }
    public static HandlerList getHandlerList() { return HANDLERS; }

    public enum Action {
        DELETE,
        CLAIM_MONEY,
        CLAIM_PACKAGE,
        ACCEPT_COD
    }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.type.MailLifecycleStatus;
import com.rismr1.mailboxgui.api.type.MailType;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.UUID;

public final class MailboxMailLifecycleEvent extends Event {
    private static final HandlerList HANDLERS = new HandlerList();
    private final UUID ownerUuid;
    private final String mailId;
    private final MailType mailType;
    private final MailLifecycleStatus status;
    private final String reason;

    public MailboxMailLifecycleEvent(UUID ownerUuid, String mailId, MailType mailType, MailLifecycleStatus status, String reason) {
        this.ownerUuid = ownerUuid;
        this.mailId = mailId;
        this.mailType = mailType;
        this.status = status;
        this.reason = reason == null ? "" : reason;
    }

    public UUID getOwnerUuid() { return ownerUuid; }
    public String getMailId() { return mailId; }
    public MailType getMailType() { return mailType; }
    public MailLifecycleStatus getStatus() { return status; }
    public String getReason() { return reason; }
    @Override public HandlerList getHandlers() { return HANDLERS; }
    public static HandlerList getHandlerList() { return HANDLERS; }
}

package com.rismr1.mailboxgui.api.event;

import com.rismr1.mailboxgui.api.model.MailboxLocation;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import java.util.UUID;

public final class MailboxRegistryChangedEvent extends Event {
    private static final HandlerList HANDLERS = new HandlerList();
    private final EntryType entryType;
    private final Action action;
    private final String entryId;
    private final UUID ownerUuid;
    private final String displayName;
    private final MailboxLocation location;

    public MailboxRegistryChangedEvent(EntryType entryType, Action action, String entryId, UUID ownerUuid,
                                       String displayName, MailboxLocation location) {
        this.entryType = entryType;
        this.action = action;
        this.entryId = entryId == null ? "" : entryId;
        this.ownerUuid = ownerUuid;
        this.displayName = displayName == null ? "" : displayName;
        this.location = location;
    }

    public EntryType getEntryType() { return entryType; }
    public Action getAction() { return action; }
    public String getEntryId() { return entryId; }
    public UUID getOwnerUuid() { return ownerUuid; }
    public String getDisplayName() { return displayName; }
    public MailboxLocation getLocation() { return location; }
    @Override public HandlerList getHandlers() { return HANDLERS; }
    public static HandlerList getHandlerList() { return HANDLERS; }

    public enum EntryType { PLAYER_MAILBOX, PUBLIC_MAILBOX, PUBLIC_ACCESS_NPC }
    public enum Action { REGISTERED, UNREGISTERED, LOAD_STATE_CHANGED }
}

package com.rismr1.mailboxgui.api.spi;

import org.bukkit.inventory.ItemStack;

public interface CustomItemCodec {
    String getId();

    int getPriority();

    boolean supports(ItemStack item);

    ItemStack prepareForStorage(ItemStack item);

    ItemStack restoreAfterStorage(ItemStack item);

    default boolean isSupportedOnCurrentBackend(ItemStack item) {
        return true;
    }
}

package com.rismr1.mailboxgui.api.spi;

import com.rismr1.mailboxgui.api.type.MailDeliveryOrigin;
import com.rismr1.mailboxgui.api.type.MailDeliveryType;
import com.rismr1.mailboxgui.api.type.MailLifecycleStatus;
import com.rismr1.mailboxgui.api.type.MailType;

import java.util.UUID;

public interface MailNotificationProvider {
    String getId();

    int getPriority();

    NotificationDecision onDelivery(NotificationContext context);

    default void onLifecycle(LifecycleNotificationContext context) {
    }

    record NotificationContext(UUID recipientUuid, String recipientName, String mailId,
                               MailDeliveryType deliveryType, MailDeliveryOrigin origin,
                               String senderName, long expiresAtMillis) {
    }

    record LifecycleNotificationContext(UUID ownerUuid, String mailId, MailType mailType,
                                        MailLifecycleStatus status, String reason) {
        public LifecycleNotificationContext {
            mailId = mailId == null ? "" : mailId;
            reason = reason == null ? "" : reason;
        }
    }

    enum NotificationDecision {
        CONTINUE,
        SUPPRESS_DEFAULT
    }
}

package com.rismr1.mailboxgui.api.message;

import org.bukkit.ChatColor;
import com.rismr1.mailboxgui.api.text.MailTextFormatting;

import java.util.ArrayList;
import java.util.List;

/** Shared rules for paper letters and attached package/money messages, not book pages. */
public final class MailMessageRules {
    public static final int MAX_VISIBLE_CHARACTERS = 256;
    public static final int LINE_WIDTH = 28;
    public static final int MAX_LINES = 17;
    /** Theoretical maximum with no automatic wrapping; not a separate /n allowance. */
    public static final int MAX_MANUAL_BREAKS = MAX_LINES - 1;

    private MailMessageRules() { }

    /** Converts /n to a newline, //n to literal /n, and accepts ordinary API/YAML newlines. */
    public static String normalize(String raw) {
        if (raw == null) return null;
        String input = raw.replace("\r\n", "\n").replace('\r', '\n');
        StringBuilder result = new StringBuilder();
        for (int i = 0; i < input.length();) {
            if (input.startsWith("//n", i)) {
                result.append("/n");
                i += 3;
            } else if (input.startsWith("/n", i)) {
                result.append('\n');
                i += 2;
            } else {
                result.append(input.charAt(i++));
            }
        }
        return result.toString();
    }

    public static Validation validate(String raw) {
        if (raw == null || raw.isBlank()) return new Validation(false, "EMPTY", 0, 0, 0);
        // Bound formatting-only input before tokenization without charging colors to the visible budget.
        if (raw.length() > 8192) return new Validation(false, "INPUT_TOO_LONG", 0, 0, 0);
        String normalized = normalize(raw);
        String plain = MailTextFormatting.plain(normalized);
        int breaks = (int) plain.chars().filter(c -> c == '\n').count();
        String visible = plain.replace("\n", "");
        int count = visible.codePointCount(0, visible.length());
        if (visible.isBlank()) return new Validation(false, "EMPTY", count, 0, breaks);
        if (count > MAX_VISIBLE_CHARACTERS) return new Validation(false, "TOO_LONG", count, 0, breaks);
        int lines = wrapNormalized(plain).size();
        return new Validation(lines <= MAX_LINES, lines > MAX_LINES ? "TOO_MANY_LINES" : "OK", count, lines, breaks);
    }

    public static boolean isValid(String raw) { return validate(raw).valid(); }

    /** Wraps supported mixed formatting without truncation; /n syntax is decoded exactly once. */
    public static List<String> wrapColored(String rawColored) {
        if (rawColored == null) return List.of();
        return List.copyOf(wrapNormalized(MailTextFormatting.legacy(normalize(rawColored))));
    }

    private static List<String> wrapNormalized(String text) {
        List<String> lines = new ArrayList<>();
        StringBuilder line = new StringBuilder();
        int width = 0;
        for (int offset = 0; offset < text.length();) {
            int cp = text.codePointAt(offset);
            if (cp == '\n') {
                lines.add(line.toString().stripTrailing());
                line = new StringBuilder(lastFormatting(line.toString()));
                width = 0;
                offset++;
                continue;
            }
            StringBuilder token = new StringBuilder();
            int tokenWidth = 0;
            boolean space = Character.isWhitespace(cp);
            while (offset < text.length()) {
                cp = text.codePointAt(offset);
                if (cp == ChatColor.COLOR_CHAR && offset + 1 < text.length()) {
                    token.append(text, offset, offset + 2);
                    offset += 2;
                    continue;
                }
                if (cp == '\n' || Character.isWhitespace(cp) != space) break;
                token.appendCodePoint(space ? ' ' : cp);
                tokenWidth++;
                offset += Character.charCount(cp);
            }
            if (space) {
                if (width > 0 && width + tokenWidth <= LINE_WIDTH) {
                    line.append(token);
                    width += tokenWidth;
                } else {
                    // Dropping boundary whitespace must not drop formatting embedded in it.
                    for (int i = 0; i + 1 < token.length(); i++) {
                        if (token.charAt(i) == ChatColor.COLOR_CHAR) {
                            line.append(token, i, i + 2);
                            i++;
                        }
                    }
                }
                continue;
            }
            if (width > 0 && width + tokenWidth > LINE_WIDTH) {
                lines.add(line.toString().stripTrailing());
                line = new StringBuilder(lastFormatting(line.toString()));
                width = 0;
            }
            for (int i = 0; i < token.length();) {
                cp = token.codePointAt(i);
                if (cp == ChatColor.COLOR_CHAR && i + 1 < token.length()) {
                    line.append(token, i, i + 2);
                    i += 2;
                    continue;
                }
                if (width == LINE_WIDTH) {
                    lines.add(line.toString().stripTrailing());
                    line = new StringBuilder(lastFormatting(line.toString()));
                    width = 0;
                }
                line.appendCodePoint(cp);
                width++;
                i += Character.charCount(cp);
            }
        }
        if (width > 0 || !line.isEmpty() || text.endsWith("\n")) lines.add(line.toString().stripTrailing());
        return lines;
    }

    private static String lastFormatting(String text) {
        String color = "";
        StringBuilder styles = new StringBuilder();
        for (int i = 0; i + 1 < text.length(); i++) {
            if (text.charAt(i) != ChatColor.COLOR_CHAR) continue;
            char code = Character.toLowerCase(text.charAt(++i));
            if (code == 'x' && i + 12 < text.length()) {
                String hex = text.substring(i - 1, i + 13);
                if (hex.matches("(?i)\u00a7x(?:\u00a7[0-9a-f]){6}")) {
                    color = hex;
                    styles.setLength(0);
                    i += 12;
                    continue;
                }
            }
            if ("0123456789abcdefr".indexOf(code) >= 0) {
                color = "" + ChatColor.COLOR_CHAR + code;
                styles.setLength(0);
            } else if ("klmno".indexOf(code) >= 0 && styles.indexOf(String.valueOf(code)) < 0) {
                styles.append(ChatColor.COLOR_CHAR).append(code);
            }
        }
        return color + styles;
    }

    public record Validation(boolean valid, String reason, int visibleCharacters, int lines, int manualBreaks) {
        /** Remaining rendered body lines, after both automatic wraps and explicit breaks. */
        public int remainingLines() { return Math.max(0, MAX_LINES - lines); }
    }
}

package com.rismr1.mailboxgui.api.text;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.minimessage.MiniMessage;
import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
import net.kyori.adventure.text.minimessage.tag.standard.StandardTags;
import net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer;
import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;

import java.util.Locale;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/** Platform-independent, non-interactive mail text formatting. Unknown tags remain literal text. */
public final class MailTextFormatting {
    private static final Set<String> SUPPORTED_FORMATS = Set.of("legacy", "hex", "minimessage-visual");
    private static final TagResolver TAGS = TagResolver.resolver(
            StandardTags.color(), StandardTags.decorations(), StandardTags.gradient(),
            StandardTags.rainbow(), StandardTags.reset());
    private static final MiniMessage MINI = MiniMessage.builder().tags(TAGS).build();
    private static final LegacyComponentSerializer LEGACY = LegacyComponentSerializer.builder()
            .character('\u00a7').hexColors().useUnusualXRepeatedCharacterHexFormat().build();
    private static final Pattern CODES = Pattern.compile(
            "(?i)[&\u00a7](?:x(?:[&\u00a7][0-9a-f]){6}|#[0-9a-f]{6}|[0-9a-fk-or])");
    private static final String[] COLORS = {"black", "dark_blue", "dark_green", "dark_aqua",
            "dark_red", "dark_purple", "gold", "gray", "dark_gray", "blue", "green", "aqua",
            "red", "light_purple", "yellow", "white"};
    private static final Pattern MINI_TAG = Pattern.compile("</?([!?#a-zA-Z0-9_-]+)(?=[:>])");
    private static final Pattern PLACEHOLDERS = Pattern.compile(
            "%[a-zA-Z_][a-zA-Z0-9_.-]*%|\\{[a-zA-Z_][a-zA-Z0-9_.-]*\\}|<([a-zA-Z_][a-zA-Z0-9_.-]*)>");

    private MailTextFormatting() { }

    /** Immutable capability identifiers. MiniMessage support is visual only, never interactive. */
    public static Set<String> supportedFormats() {
        return SUPPORTED_FORMATS;
    }

    /** Converts supported formatting to section-sign legacy text, preserving /n and literal placeholders. */
    public static String legacy(String input) {
        if (input == null || input.isEmpty()) return "";
        if (!hasFormattingTags(input)) return legacyCodes(input);
        try {
            ProtectedInput protectedInput = protectPlaceholders(input);
            return protectedInput.restore(LEGACY.serialize(parse(protectedInput.text())));
        } catch (RuntimeException invalidFormatting) {
            return legacyCodes(input);
        }
    }

    /** Returns visible text without supported formatting; does not decode mail line-break syntax. */
    public static String plain(String input) {
        if (input == null || input.isEmpty()) return "";
        if (!hasFormattingTags(input)) return CODES.matcher(input).replaceAll("");
        try {
            ProtectedInput protectedInput = protectPlaceholders(input);
            return protectedInput.restore(PlainTextComponentSerializer.plainText().serialize(parse(protectedInput.text())));
        } catch (RuntimeException invalidFormatting) {
            return CODES.matcher(input).replaceAll("");
        }
    }

    /** Inserts independently formatted text without leaking its style into the surrounding template. */
    public static String replaceIsolated(String template, String placeholder, String value) {
        String rendered = legacy(template);
        String replacement = legacy(value);
        if (placeholder == null || placeholder.isEmpty()) return rendered;
        if (!CODES.matcher(replacement).find()) return rendered.replace(placeholder, replacement);
        StringBuilder result = new StringBuilder();
        int start = 0;
        int index;
        while ((index = rendered.indexOf(placeholder, start)) >= 0) {
            result.append(rendered, start, index).append(replacement).append("\u00a7r")
                    .append(activeLegacyStyle(rendered.substring(0, index)));
            start = index + placeholder.length();
        }
        return result.append(rendered.substring(start)).toString();
    }

    private static String activeLegacyStyle(String prefix) {
        Matcher codes = CODES.matcher(prefix);
        String color = "";
        StringBuilder decorations = new StringBuilder();
        while (codes.find()) {
            String code = codes.group().substring(1).toLowerCase(Locale.ROOT);
            if (code.equals("r")) {
                color = "";
                decorations.setLength(0);
            } else if (code.startsWith("x") || code.startsWith("#") || "0123456789abcdef".contains(code)) {
                color = legacyCodes(codes.group());
                decorations.setLength(0);
            } else if (decorations.indexOf("\u00a7" + code) < 0) {
                decorations.append('\u00a7').append(code);
            }
        }
        return color + decorations;
    }

    // Gradients color each character. One private-use character keeps late String.replace tokens intact.
    private static ProtectedInput protectPlaceholders(String input) {
        Matcher matcher = PLACEHOLDERS.matcher(input);
        Map<String, String> originals = new LinkedHashMap<>();
        StringBuilder result = new StringBuilder();
        int sentinelCodePoint = 0xe000;
        while (matcher.find()) {
            String angleName = matcher.group(1);
            if (angleName != null && TAGS.has(angleName.toLowerCase(Locale.ROOT))) continue;
            String sentinel;
            do {
                if (sentinelCodePoint == 0xf900) sentinelCodePoint = 0xf0000;
                sentinel = new String(Character.toChars(sentinelCodePoint++));
            } while (input.contains(sentinel));
            originals.put(sentinel, matcher.group());
            matcher.appendReplacement(result, Matcher.quoteReplacement(sentinel));
        }
        matcher.appendTail(result);
        return new ProtectedInput(result.toString(), originals);
    }

    private record ProtectedInput(String text, Map<String, String> originals) {
        String restore(String rendered) {
            for (var entry : originals.entrySet()) rendered = rendered.replace(entry.getKey(), entry.getValue());
            return rendered;
        }
    }

    private static boolean hasFormattingTags(String input) {
        Matcher tags = MINI_TAG.matcher(input);
        while (tags.find()) {
            if (TAGS.has(tags.group(1).toLowerCase(Locale.ROOT))) return true;
        }
        return false;
    }

    private static String legacyCodes(String input) {
        Matcher matcher = CODES.matcher(input);
        StringBuilder result = new StringBuilder();
        while (matcher.find()) {
            String code = matcher.group().substring(1).toLowerCase(Locale.ROOT);
            String replacement;
            if (code.charAt(0) == '#') {
                StringBuilder hex = new StringBuilder("\u00a7x");
                for (int i = 1; i < code.length(); i++) hex.append('\u00a7').append(code.charAt(i));
                replacement = hex.toString();
            } else {
                replacement = "\u00a7" + code.replace('&', '\u00a7');
            }
            matcher.appendReplacement(result, Matcher.quoteReplacement(replacement));
        }
        matcher.appendTail(result);
        return result.toString();
    }

    private static Component parse(String input) {
        if (input == null || input.isEmpty()) return Component.empty();
        Matcher matcher = CODES.matcher(input);
        StringBuilder converted = new StringBuilder();
        while (matcher.find()) {
            String code = matcher.group().substring(1).toLowerCase(Locale.ROOT);
            String tag;
            if (code.charAt(0) == 'x') {
                StringBuilder hex = new StringBuilder("#");
                for (int i = 2; i < code.length(); i += 2) hex.append(code.charAt(i));
                tag = "<reset><" + hex + ">";
            } else if (code.charAt(0) == '#') {
                tag = "<reset><" + code + ">";
            } else {
                int color = "0123456789abcdef".indexOf(code);
                tag = color >= 0 ? "<reset><" + COLORS[color] + ">" : switch (code) {
                    case "k" -> "<obfuscated>";
                    case "l" -> "<bold>";
                    case "m" -> "<strikethrough>";
                    case "n" -> "<underlined>";
                    case "o" -> "<italic>";
                    default -> "<reset>";
                };
            }
            matcher.appendReplacement(converted, Matcher.quoteReplacement(tag));
        }
        matcher.appendTail(converted);
        return MINI.deserialize(converted.toString());
    }
}

package com.rismr1.mailboxgui.api.network;

import com.rismr1.mailboxgui.api.type.NetworkDeliveryTarget;
import java.util.Optional;
import java.util.Set;
import java.util.UUID;

// Read-only public excerpt; owner-only companion methods are deliberately omitted.
public interface MailboxNetworkApi {
    int getApiVersion();
    Set<NetworkCapability> getCapabilities();
    /** Stable backend scope, not an exactly-once delivery guarantee. */
    String getIdempotencyScope();
    NetworkSnapshot getSnapshot();
    /** Read-only cached effective icon configuration. Older providers may not support this accessor. */
    default NetworkGuiSnapshot getGuiConfiguration() {
        throw new UnsupportedOperationException("gui-configuration-unsupported");
    }
    Optional<NetworkPresenceSnapshot> getPresence(UUID playerId);
    NetworkEligibilitySnapshot getEligibility(NetworkDeliveryTarget target);
}

package com.rismr1.mailboxgui.api.network;

// Public read-only capabilities; this excerpt omits owner-only companion capabilities.
public enum NetworkCapability {
    CACHED_SNAPSHOTS, BACKEND_GROUPS, PLAYER_PRESENCE, ROUTING_ELIGIBILITY,
    STABLE_BACKEND_SCOPE, SNAPSHOT_EVENTS, GUI_CONFIGURATION
}

package com.rismr1.mailboxgui.api.network;

import java.util.List;

/** status: disabled, starting, ready, degraded, stopped, stale (legacy: available/unavailable).
 * Use available rather than comparing display status strings. Time is Unix milliseconds. */
public record NetworkSnapshot(long capturedAtMillis, long generation, String localBackendId,
        boolean enabled, boolean started, boolean available, String status,
        List<NetworkBackendSnapshot> backends, List<NetworkGroupSnapshot> groups,
        List<NetworkPresenceSnapshot> presence, int onlineCount, int staleBackendCount) {
    public NetworkSnapshot {
        backends = List.copyOf(backends);
        groups = List.copyOf(groups);
        presence = List.copyOf(presence);
    }
}

package com.rismr1.mailboxgui.api.network;

public record NetworkBackendSnapshot(String serverId, String serverDisplayName,
        String minecraftVersion, String bukkitVersion, int bukkitDataVersion,
        String mailboxGuiVersion, int mailboxDataVersion, int networkProtocolVersion,
        int packageManifestVersion, String serializerProfile, String storageType,
        boolean vaultAvailable, boolean packageClaimSupported, boolean codClaimSupported,
        boolean bookLetterSupported, boolean moneyMailSupported,
        long profileCreatedAtMillis, boolean localBackend, boolean stale) {
}

package com.rismr1.mailboxgui.api.network;

import java.util.List;

public record NetworkGroupSnapshot(String name, List<String> members) {
    public NetworkGroupSnapshot { members = List.copyOf(members); }
}

package com.rismr1.mailboxgui.api.network;

import java.util.UUID;

public record NetworkPresenceSnapshot(UUID playerId, String playerName, String backendId,
        String backendDisplayName, String worldName, boolean online,
        long lastSeenAtMillis, long heartbeatAtMillis, boolean stale) {
}

package com.rismr1.mailboxgui.api.network;

import java.util.List;

/** reason: eligible, network_disabled, network_unavailable, invalid_target,
 * unknown_backend, unknown_group, no_eligible_backend. Stale backends are never eligible.
 */
public record NetworkEligibilitySnapshot(long capturedAtMillis, long generation,
        boolean eligible, String reason, List<String> eligibleBackendIds) {
    public NetworkEligibilitySnapshot { eligibleBackendIds = List.copyOf(eligibleBackendIds); }
}

package com.rismr1.mailboxgui.api.network;

/** Immutable, cache-only effective themed-icon configuration, never layouts or player pack status.
 * scope: disabled, single-server, shared, backend-local.
 * ready means an effective configuration is available, not merely that customization is enabled.
 * Disabled snapshots have ready=false and an empty fingerprint. A shared scope may be unready
 * while awaiting its authority. sharedMainBackend is the resolved publisher, or its configured
 * policy before publication (empty means first publisher); it is empty outside shared scope.
 * Fingerprints are opaque configuration identities.
 */
public record NetworkGuiSnapshot(String scope, String backendId, String sharedMainBackend,
                                 String fingerprint, boolean ready) {
}

package com.rismr1.mailboxgui.api.network;

import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

/** Main-thread notification after an immutable snapshot is published. Not cancellable. */
public final class MailboxNetworkSnapshotEvent extends Event {
    private static final HandlerList HANDLERS = new HandlerList();
    private final NetworkSnapshot snapshot;
    public MailboxNetworkSnapshotEvent(NetworkSnapshot snapshot) { this.snapshot = snapshot; }
    public NetworkSnapshot getSnapshot() { return snapshot; }
    @Override public HandlerList getHandlers() { return HANDLERS; }
    public static HandlerList getHandlerList() { return HANDLERS; }
}