qSecuritySystem API

qsecuritysystem-api is the official integration layer for qSecuritySystem. It gives third-party plugins and services a stable, typed contract to interact with moderation features without direct access to internal managers or database code.

API Documentation: https://www.notion.so/qSecuritySystem-API-e7c8491911224624b257043711a20fc5

Why this API exists

Keep integrations stable across plugin updates
Allow modular addon development
Support external systems (web panels, backend services, bots)
Prevent unsafe coupling to internal implementation details

Core capabilities

Punishment Management

Check active bans/mutes
Issue and remove punishments
Read punishment history
Work with temporary and permanent punishments

Reports System

Create reports
Read open/closed reports
Close reports
Track report lifecycle via typed models

Player Check System

Start and finish checks
Inspect active checks
Read check history

Moderation Tools Contract

Freeze/unfreeze hooks
Vanish hooks
Staff-mode/flags/notes extension points

Note: some moderation/staff-log operations are contract-ready in the API but may be limited by the current plugin storage schema.

Staff Logs Contract

Record moderation actions
Query staff activity by actor or target
Retrieve recent moderation events

Runtime initialization

The API artifact now includes its own lightweight Bukkit bootstrap plugin (qSecuritySystemAPI) with plugin.yml. This guarantees the API jar initializes cleanly when installed on the server.

qSecuritySystemAPI exposes contracts and startup diagnostics
qSecuritySystem (core plugin) remains the actual API provider and registers QSecuritySystemApi in ServicesManager

ServiceManager integration

The plugin registers QSecuritySystemApi in Bukkit ServicesManager at startup. Any integration plugin can obtain the API provider like this:

RegisteredServiceProvider<QSecuritySystemApi> provider = Bukkit.getServicesManager()
        .getRegistration(QSecuritySystemApi.class);
if (provider != null) {
    QSecuritySystemApi api = provider.getProvider();
}

Supported API methods (current implementation)

Below is what the current QSecuritySystemApiProvider supports at runtime.

`PunishmentApi`

isBanned, isMuted, hasActivePunishment
getActivePunishment, getActivePunishments
getPunishmentHistory, getPunishmentHistory(UUID, type), getPunishmentCount
issuePunishment (BAN/MUTE/KICK)
removePunishment (BAN/MUTE)
getRemainingTime

`ReportApi`

createReport
getOpenReports, getReportById
closeReport, isReportOpen
getReportsByTarget, getReportsByReporter

Limitations:

claimReport is currently contract-level only and returns unsupported message in provider implementation.

`CheckApi`

startCheck (requires online player + online staff)
endCheck, failCheck
isUnderCheck, getActiveCheck, getActiveChecks
getCheckHistory

`PlayerSecurityApi`

getProfile, getSnapshot
isFrozen, isVanished, isStaffModeEnabled, isFlagged

Limitations:

isStaffModeEnabled/isFlagged currently return false in provider implementation (reserved extension points).

`ModerationToolApi`

isFrozen, isVanished
setVanished
setFrozen (unfreeze via check termination is supported)

Limitations:

setStaffMode, setFlag, addNote, and manual freeze enable are currently contract-level only.

`StaffLogApi`

record
getByStaff, getByTarget, getRecent

Implementation detail:

Staff logs are currently in-memory in provider implementation.

Architecture guarantees

The API module contains only public integration primitives:

interfaces
data models / records
enums
result objects

This separation keeps plugin internals flexible while preserving a predictable integration contract.