qSecuritySystem API

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.