API для разработчиков

API находится в jar плагина — подключите его как provided/compileOnly зависимость и укажите FinExBans в softdepend / depend.

Точка входа

import uz.finex.bans.api.FinExBansAPI;

if (FinExBansAPI.available()) {
    FinExBansAPI api = FinExBansAPI.get();
}

Наказания

Каждый вызов возвращает CompletableFuture, который завершается в IO-потоке плагина. Длительности в миллисекундах; FinExBansAPI.PERMANENT — бессрочно. operator может быть null для консоли.

api.ban(uuid, "Cheating", Duration.parse("30d"), staffUuid, "Moder_Ali", false);
api.mute(uuid, "Spam", 3_600_000L, null, "MyPlugin", true);   // тихо
api.warn(uuid, "Caps", null, "MyPlugin", false);
api.kick(uuid, "AFK", null, "MyPlugin", false);
api.ipBan(uuid, "Bot", FinExBansAPI.PERMANENT, null, "AntiBot", false);

// по нику — незнакомые ники определяются как в /ban
api.punishByName(PunishmentType.BAN, "Steve", "Cheating", FinExBansAPI.PERMANENT, null, "MyPlugin", false);

Игрок кикается/уведомляется, наказание объявляется, вебхуки срабатывают — ровно как при команде.

Снятие

api.pardon(PunishmentType.BAN, uuid, staffUuid, "Moder_Ali", "Апелляция принята")
   .thenAccept(rows -> { /* rows == 0 → активного не было */ });

Запросы

boolean muted = api.isMuted(uuid);                         // мгновенно, из кеша (онлайн-игроки)
api.activeBan(uuid).thenAccept(opt -> opt.ifPresent(p -> ...));
api.activeIpBan("1.2.3.4");
api.history(uuid, 50).thenAccept(list -> ...);
api.warnings(uuid, System.currentTimeMillis() - 30L * 86_400_000).thenAccept(count -> ...);
api.alts(uuid).thenAccept(alts -> ...);                    // List<Database.Alt>: name, sharedIps, lastSeen

У Punishment есть getType(), getTarget(), getTargetName(), getIp(), getReason(), getOperator(), getOperatorName(), getCreatedAt(), getExpiresAt(), isPermanent(), isSilent(), isCurrentlyActive(now), remaining(now), getServer(), getId().

События

Слушатель, не зависящий от платформы (Paper, Velocity, Bungee):

api.addListener(new PunishmentListener() {
    @Override public void onPunish(Punishment p) { ... }
    @Override public void onPardon(PunishmentType type, UUID uuid, String ip, long id,
                                   UUID operator, String operatorName, String reason) { ... }
});

Оба колбэка выполняются в IO-потоке — вернитесь в планировщик своей платформы, прежде чем трогать мир.

На Paper та же информация приходит и как события Bukkit:

@EventHandler
public void on(uz.finex.bans.paper.event.PunishmentEvent e) { e.getPunishment(); }

@EventHandler
public void on(uz.finex.bans.paper.event.PardonEvent e) { e.getType(); e.getTarget(); }

Оба события асинхронные (isAsynchronous() == true).