Developer API

The API lives in the plugin jar — add it to your build as a provided/compileOnly dependency and declare FinExBans in softdepend / depend.

Entry point

import uz.finex.bans.api.FinExBansAPI;

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

Punishing

Every call returns a CompletableFuture that completes on the plugin's IO thread. Durations are milliseconds; FinExBansAPI.PERMANENT means no expiry. operator may be null for the console.

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

// by name — unknown names are resolved like /ban does
api.punishByName(PunishmentType.BAN, "Steve", "Cheating", FinExBansAPI.PERMANENT, null, "MyPlugin", false);

The player is kicked/notified, the punishment is broadcast and webhooks fire — exactly as with the command.

Lifting

api.pardon(PunishmentType.BAN, uuid, staffUuid, "Moder_Ali", "Appeal accepted")
   .thenAccept(rows -> { /* rows == 0 → nothing was active */ });

Queries

boolean muted = api.isMuted(uuid);                         // instant, cache (online players)
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 exposes getType(), getTarget(), getTargetName(), getIp(), getReason(), getOperator(), getOperatorName(), getCreatedAt(), getExpiresAt(), isPermanent(), isSilent(), isCurrentlyActive(now), remaining(now), getServer(), getId().

Listening

Platform-neutral listener (works on Paper, Velocity and 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) { ... }
});

Both callbacks run on the IO thread — schedule back to your platform before touching the world.

On Paper the same information is also fired as Bukkit events:

@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(); }

Both are asynchronous events (isAsynchronous() == true).