# Developer API Reference

Verité exposes a stable public Java API under the package `teacommontea.api`. Every subsystem is a facade of static methods over stable public types, so you can do everything the plugin does without ever referencing an internal implementation class.

This page is the full surface, organised for lookup. Two topics have their own dedicated guides and are only cross-linked here:

- The chat filter: [Custom Chat Integration](page:developers/wiring).
- Mute, slowmode, and freeze enforcement: [Custom Moderation Enforcement](page:developers/moderation-enforcement).

## Getting Started

### Add Verité as a soft dependency

Add Verité to your `plugin.yml` so it loads before your plugin when installed, without becoming mandatory:

```yaml
softdepend:
  - Verite
```

### Guard for availability

If Verité is optional, check for a class before touching the API:

```java
private static final boolean VERITE_AVAILABLE;

static {
    boolean available;
    try {
        Class.forName("teacommontea.api.VeriteAPI");
        available = true;
    } catch (ClassNotFoundException ignored) {
        available = false;
    }
    VERITE_AVAILABLE = available;
}
```

Every subsystem also degrades on its own: when the backing module is disabled, query methods return `null`, `false`, or an empty collection, mutating calls become no-ops, and issuing calls return a failed result. You rarely have to special-case a disabled module.

## VeriteAPI

`VeriteAPI` is the single umbrella entry point. It reports the API version, reports which modules are enabled, and returns the class of each subsystem for discovery.

| Member | Returns | Meaning |
| --- | --- | --- |
| `VeriteAPI.VERSION` | `String` | The API version string. |
| `moderationEnabled()` | `boolean` | Whether the moderation module is loaded. |
| `vanishEnabled()` | `boolean` | Whether the vanish module is loaded. |
| `captchaEnabled()` | `boolean` | Whether the captcha module is loaded. |
| `moderation()` | `Class<VeriteModeration>` | The moderation subsystem class. |
| `playerData()` | `Class<VeritePlayerData>` | The player-data subsystem class. |
| `store()` | `Class<VeriteStore>` | The store subsystem class. |
| `vanish()` | `Class<VeriteVanish>` | The vanish subsystem class. |
| `captcha()` | `Class<VeriteCaptcha>` | The captcha subsystem class. |
| `filter()` | `Class<VeriteFilter>` | The chat filter subsystem class. |
| `text()` | `Class<VeriteText>` | The text formatting subsystem class. |

All subsystems are static facades, so you call them directly (for example `VeriteModeration.isBanned(uuid)`). The accessor methods exist for discovery and centralised enabled checks.

## VeriteModeration

The complete entry point for issuing, querying, and lifting punishments. `durationMillis` uses `Punishment.PERMANENT` for a permanent punishment. Gate methods return `true` when they stopped the player. See [Custom Moderation Enforcement](page:developers/moderation-enforcement) for the gate and listener workflow in depth.

### Status and queries

| Method | Returns | Meaning |
| --- | --- | --- |
| `enabled()` | `boolean` | Whether the moderation module is loaded. |
| `isBanned(UUID player)` | `boolean` | Whether the player has an active ban. |
| `isMuted(UUID player)` | `boolean` | Whether the player has an active mute. |
| `activeBan(UUID player)` | `Punishment` | The active ban, or `null`. |
| `activeMute(UUID player)` | `Punishment` | The active mute, or `null`. |
| `history(UUID player, int limit)` | `List<Punishment>` | Recent punishment history for the player. |
| `byIp(String ip, int limit)` | `List<Punishment>` | Punishments recorded against an ip. |
| `byStaff(UUID staff, int limit)` | `List<Punishment>` | Punishments issued by a staff member. |
| `activeWarnings(UUID player)` | `List<Punishment>` | Currently-active warnings for the player. |
| `activePunishments()` | `List<ActivePunishment>` | Lightweight pointers to every active punishment. |
| `activeOfType(PunishmentType type, long now)` | `List<Punishment>` | Active punishments of a type at a given time. |
| `loadPunishment(long id)` | `Punishment` | The full record for a numeric id, or `null`. |
| `altsOf(UUID player)` | `List<UUID>` | Accounts sharing the player's first known ip. |
| `pruneHistory(UUID player, long cutoff, long now)` | `int` | Removes history older than the cutoff, returns the count removed. |
| `warningExpire()` | `long` | The warning expiry window in milliseconds. |

### Issuing punishments

| Method | Returns |
| --- | --- |
| `ban(UUID target, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)` | `PunishmentResult` |
| `mute(UUID target, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)` | `PunishmentResult` |
| `ipban(UUID target, String ip, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)` | `PunishmentResult` |
| `ipmute(UUID target, String ip, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)` | `PunishmentResult` |
| `warn(UUID target, String targetName, String reason, UUID executor, String executorName, boolean silent)` | `PunishmentResult` |
| `kick(UUID target, String targetName, String reason, UUID executor, String executorName, boolean silent)` | `PunishmentResult` |

### Lifting punishments

| Method | Returns | Meaning |
| --- | --- | --- |
| `unban(UUID target, String targetName, UUID remover, String removerName, String reason)` | `boolean` | Lifts the active ban, `true` on success. |
| `unmute(UUID target, String targetName, UUID remover, String removerName, String reason)` | `boolean` | Lifts the active mute, `true` on success. |
| `unwarn(UUID target, String targetName, UUID removedBy, String removedByName, String reason)` | `PunishmentResult` | Removes a warning. |

### Rendering and notices

| Method | Returns | Meaning |
| --- | --- | --- |
| `banScreen(Punishment ban)` | `String` | The full ban screen for a ban record. |
| `muteLine(Punishment mute)` | `String` | The one-line mute summary. |
| `muteNotice(Punishment mute)` | `String` | The mute notice sent to a muted player. |

### Chat gates

Each gate returns `true` when the player should be stopped and sends them the reason as a side effect. Use them where you intend to enforce.

| Method | Returns | Meaning |
| --- | --- | --- |
| `muteGate(Player p)` | `boolean` | Player is muted; sends the mute notice. |
| `chatMuteGate(Player p)` | `boolean` | Global chat freeze is active; sends the frozen notice. |
| `slowmodeGate(Player p)` | `boolean` | Player is held by slowmode; sends the remaining wait. |

### Chat commands

These drive the plugin's own chat commands for a `CommandSender`.

| Method | Meaning |
| --- | --- |
| `broadcast(CommandSender sender, String[] args)` | Sends a broadcast. |
| `chatClear(CommandSender sender)` | Clears chat. |
| `chatMute(CommandSender sender)` | Toggles the global chat freeze. |
| `slowmode(CommandSender sender, String[] args)` | Sets slowmode. |

### Listener

| Method | Meaning |
| --- | --- |
| `registerListener(ModerationListener listener)` | Subscribe to punishment activity. |
| `unregisterListener(ModerationListener listener)` | Stop receiving events. |

## VeritePlayerData

Read and record the account, session, and identity data the moderation system stores. Timestamps are epoch milliseconds. When the module is disabled, queries return `null` or empty and record calls are no-ops.

| Method | Returns | Meaning |
| --- | --- | --- |
| `enabled()` | `boolean` | Whether the data store is open. |
| `hasProfile(UUID player)` | `boolean` | Whether a profile exists. |
| `profile(UUID player)` | `PlayerProfile` | The full profile, or `null`. |
| `uuidByName(String name)` | `UUID` | Resolve a uuid from a name. |
| `nameOf(UUID player)` | `String` | Resolve the current name from a uuid. |
| `knownNames()` | `List<String>` | Every known name in the store. |
| `namesOf(UUID player)` | `List<String>` | All names a player has used. |
| `ipsOf(UUID player)` | `List<String>` | All ips a player has connected from. |
| `usersOfIp(String ip)` | `List<UUID>` | All users who shared an ip. |
| `clientsOf(UUID player)` | `List<String>` | All clients a player has used. |
| `recordLogin(UUID player, String name, String ip, long now)` | `void` | Record a login. |
| `recordClient(UUID player, String brand, int protocol, String referrer, long now)` | `void` | Record a client brand and protocol. |
| `flushSession(UUID player, long now)` | `void` | Flush the player's session. |
| `recordLogout(UUID player, long now)` | `void` | Record a logout. |

## VeriteStore and VeriteScope

`VeriteStore` opens named data scopes in the plugin's shared persistent key-value store, so your plugin can persist data alongside Verité with no database of its own. Namespace your scope names to avoid collisions with plugin data.

| `VeriteStore` method | Returns | Meaning |
| --- | --- | --- |
| `available()` | `boolean` | Whether the store is open. |
| `scope(String name)` | `VeriteScope` | Opens a named scope, or `null` if unavailable. |

A `VeriteScope` is a named area you read and write freely. Writes persist through the plugin's normal flush cycle.

| `VeriteScope` method | Returns | Meaning |
| --- | --- | --- |
| `set(String key, Object value)` | `void` | Store a value under a key. |
| `delete(String key)` | `void` | Remove a key. |
| `has(String key)` | `boolean` | Test key presence. |
| `get(String key)` | `Object` | The raw stored value. |
| `getString(String key, String def)` | `String` | Typed read with a default. |
| `getLong(String key, long def)` | `long` | Typed read with a default. |
| `getInt(String key, int def)` | `int` | Typed read with a default. |
| `getBoolean(String key, boolean def)` | `boolean` | Typed read with a default. |
| `getBigDecimal(String key)` | `BigDecimal` | Typed read. |
| `entries()` | `List<ScopeEntry>` | Every key-value pair in the scope. |

```java
VeriteScope scope = VeriteStore.scope("myplugin");
if (scope != null) {
    scope.set("greeting", "hello");
    String greeting = scope.getString("greeting", "");
}
```

## VeriteVanish

Staff vanish state and control. `vanish`, `unvanish`, and `toggle` return `true` when the state actually changed. When the module is disabled, queries return `false` or empty and mutating calls are no-ops.

| Method | Returns | Meaning |
| --- | --- | --- |
| `enabled()` | `boolean` | Whether the vanish module is loaded. |
| `isVanished(UUID player)` | `boolean` | Whether a player is vanished. |
| `isVanished(Player player)` | `boolean` | Convenience overload for an online player. |
| `getVanished()` | `Set<UUID>` | Every currently-vanished player. |
| `vanish(Player p)` | `boolean` | Vanish a player. |
| `unvanish(Player p)` | `boolean` | Unvanish a player. |
| `toggle(Player p)` | `boolean` | Toggle a player's vanish state. |
| `registerPlaceholders()` | `void` | Register the vanish PlaceholderAPI expansion. |
| `registerListener(VanishListener listener)` | `void` | Subscribe to vanish changes. |
| `unregisterListener(VanishListener listener)` | `void` | Stop receiving vanish events. |

## VeriteCaptcha

Issue and track captcha challenges. `challenge` methods return `true` when a challenge was actually started. The `source` label records why the challenge was opened and rides through to the completion and punishment-request events. When the module is disabled, all calls return `false`.

| Member | Returns | Meaning |
| --- | --- | --- |
| `VeriteCaptcha.BYPASS_PERMISSION` | `String` | The permission node that bypasses captcha. |
| `VeriteCaptcha.NOTIFY_PERMISSION` | `String` | The captcha notify permission node. |
| `enabled()` | `boolean` | Whether the captcha module is loaded. |
| `isActive(UUID player)` | `boolean` | Whether a challenge is active for the player. |
| `challengeStandard(Player player, String source)` | `boolean` | Open a standard challenge. |
| `challengeDetailed(Player player, String source)` | `boolean` | Open a detailed challenge. |
| `challenge(Player player, CaptchaType type, String source)` | `boolean` | Open a challenge of an explicit type. |

## VeriteFilter

The evasion-aware chat filter. Full workflow, including anonymous checks, repeat-aware checks, and the block message helpers, is documented in [Custom Chat Integration](page:developers/wiring). The surface:

| Member | Returns | Meaning |
| --- | --- | --- |
| `VeriteFilter.ANONYMOUS` | `UUID` | Pass as the player when there is no offender to record against. |
| `check(UUID player, String message)` | `FilterResult` | Classify a message and record the hit against the player. |
| `check(UUID player, String message, boolean repeatAware)` | `FilterOutcome` | Repeat-aware classification. |
| `count(UUID player)` | `int` | How many times a player has been flagged. |
| `blockMessage()` | `String` | The configured block message. |
| `repeatMessage()` | `String` | The configured repeat-message notice. |
| `selfHarmMessage()` | `String` | The configured self-harm notice. |
| `blockNotice(FilterResult result, String message)` | `BaseComponent[]` | The rendered notice component for a result. |
| `foldAccents(String s)` | `String` | Normalization helper: remove accents. |
| `stripDeletes(String s)` | `String` | Normalization helper: remove zero-width and delete characters. |
| `stripEntities(String s)` | `String` | Normalization helper: remove html-style entities. |
| `reduceRuns(String s, int max)` | `String` | Normalization helper: collapse repeated letters. |
| `fingerprint(String word)` | `String` | Order-independent letter signature for transposition matching. |
| `trimEdges(String word)` | `String` | Trim non-letter edges from a word. |

The normalization helpers are pure functions and are safe to call off the main thread.

## VeriteText

Parse Verite tag text and apply the plugin's prefix the way the plugin does, so your output is styled identically.

| Method | Returns | Meaning |
| --- | --- | --- |
| `parse(String tagged)` | `BaseComponent[]` | Parse Verite tags to a component array. |
| `prefixed(String tagged)` | `BaseComponent[]` | Parse and prepend the plugin prefix. |
| `prefix()` | `String` | The current prefix. |
| `setPrefix(String prefix)` | `void` | Change the prefix. |

## Utilities

### VeriteGeoIp

Look up the country of an ip and check the GeoIP database state.

| Method | Returns | Meaning |
| --- | --- | --- |
| `country(String ip)` | `String` | Country name for an ip, or `null` if unresolved. |
| `available()` | `boolean` | Whether the GeoIP database loaded. |
| `isPrivate(String ip)` | `boolean` | Whether an ip is in a private or reserved range. |
| `attempted()` | `boolean` | Whether a database load has been attempted. |

### VeriteDuration

Parse and format human punishment durations, with millisecond unit constants: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`.

| Method | Returns | Meaning |
| --- | --- | --- |
| `suggestions()` | `List<String>` | Suggested duration tokens. |
| `parse(String token)` | `long` | Parse a token such as `7d` into milliseconds. |
| `parseTwoToken(String number, String unitWord)` | `long` | Parse a split number and unit word into milliseconds. |
| `format(long millis)` | `String` | Format milliseconds into a human string. |

### VeriteFormat

Format times, pluralize nouns, and name client protocol versions.

| Method | Returns | Meaning |
| --- | --- | --- |
| `fancyTime(long millis)` | `String` | A millisecond span as a human string. |
| `plural(long count, String noun)` | `String` | A count with the correct singular or plural noun. |
| `pluralize(long count, String noun)` | `String` | A count with the correct singular or plural noun. |
| `versionName(int protocol)` | `String` | The Minecraft version name for a client protocol number. |

### VeriteLimits

Enforce the same per-issuer duration caps and cooldowns the plugin does.

| Method | Returns | Meaning |
| --- | --- | --- |
| `capDuration(CommandSender issuer, PunishmentType type, long requested)` | `DurationCheck` | Validate a requested duration and return the capped value. |
| `cooldownRemaining(CommandSender issuer, PunishmentType type, long now)` | `long` | Milliseconds until the issuer may act again. |
| `markUsed(CommandSender issuer, PunishmentType type, long now)` | `void` | Record that an issuer used their allowance. |

### VeriteMojang

Resolve a Minecraft username against Mojang, using the same path and cache the plugin uses.

| Method | Returns | Meaning |
| --- | --- | --- |
| `lookup(String name)` | `MojangProfile` | Resolve a name to a uuid, canonical name, and status. |

### VeriteExempt

Check whether an issuer is blocked from punishing a target.

| Method | Returns | Meaning |
| --- | --- | --- |
| `blockReason(CommandSender issuer, UUID target, PunishmentType type)` | `String` | The reason the punishment is not permitted, or `null` when allowed. |

### VeriteLockdown

Query and control server lockdown state. Covered in context in [Custom Moderation Enforcement](page:developers/moderation-enforcement).

| Method | Returns | Meaning |
| --- | --- | --- |
| `active()` | `boolean` | Whether a lockdown is in effect. |
| `reason()` | `String` | The current lockdown reason. |
| `begin(String why)` | `void` | Start a lockdown with a reason. |
| `end()` | `void` | Clear the lockdown. |

### VeriteConfig

Read the moderation module's effective configuration.

| Method | Returns | Meaning |
| --- | --- | --- |
| `banAlts()` | `boolean` | Whether alt accounts are banned. |
| `muteCommandBlacklist()` | `List<String>` | Commands blocked while muted. |
| `warningExpire()` | `long` | The warning expiry window in milliseconds. |
| `useGroupWeights()` | `boolean` | Whether group weights are used. |
| `permitSameWeight()` | `boolean` | Whether same-weight actions are permitted. |
| `reduceToLimit()` | `boolean` | Whether durations reduce to the issuer limit. |
| `dupeipScanLimit()` | `int` | The dupeip scan limit. |
| `yaml()` | `YamlConfiguration` | The raw backing configuration. |

## Types

### Punishment

An immutable moderation record. `PERMANENT` is the sentinel end timestamp for a permanent punishment (`-1L`). `GLOBAL_SCOPE` is the wildcard scope (`"*"`). Timestamps are epoch milliseconds. A `null` target ip means the punishment is uuid-scoped rather than ip-scoped.

Accessors: `id()`, `randomId()`, `type()`, `uuid()`, `ip()`, `reason()`, `executorUuid()`, `executorName()`, `removedByUuid()`, `removedByName()`, `removalReason()`, `dateStart()`, `dateEnd()`, `serverScope()`, `serverOrigin()`, `template()`, `silent()`, `ipban()`, `active()`.

Derived helpers:

| Method | Returns | Meaning |
| --- | --- | --- |
| `permanent()` | `boolean` | Whether `dateEnd` is `PERMANENT`. |
| `expired(long now)` | `boolean` | Whether a temporary punishment has passed its end. |
| `inForce(long now)` | `boolean` | Whether the record is active and not expired. |
| `duration()` | `long` | Total duration, or `PERMANENT`. |
| `remaining(long now)` | `long` | Remaining milliseconds, or `PERMANENT`. |
| `hasTemplate()` | `boolean` | Whether the record carries a template. |

### PunishmentType

Enum: `BAN`, `MUTE`, `WARNING`, `KICK`.

| Method | Returns | Meaning |
| --- | --- | --- |
| `id()` | `String` | The lowercase root-locale name. |
| `PunishmentType.of(String s)` | `PunishmentType` | Parse the lowercase form back, case-insensitively. |

### PunishmentResult

Record: `PunishmentResult(boolean ok, Punishment entry, String error)`. On success `ok` is `true`, `entry` holds the resulting punishment, and `error` is `null`. On failure `entry` is `null` and `error` holds the reason.

### ActivePunishment

Record: `ActivePunishment(PunishmentType type, UUID uuid, long entryId)`. A lightweight pointer; load the full record with `VeriteModeration.loadPunishment(entryId)`.

### FilterResult

Enum: `CLEAN`, `BLOCK`, `SELF_HARM`, `ABUSE`, `PROFANITY`. `blocks()` returns `true` for anything other than `CLEAN`. A message stopped for repeating a recent one reports as `BLOCK` here; use the repeat-aware `check` overload to tell those apart. `SELF_HARM` and `ABUSE` mark a speaker who may be in crisis; do not treat them as ordinary rule violations.

### FilterOutcome

The value from `VeriteFilter.check(player, message, true)`.

| Method | Returns | Meaning |
| --- | --- | --- |
| `category()` | `FilterResult` | The ordinary filter category, never `null`. |
| `repeat()` | `boolean` | Whether the block was a repeat (only ever `true` when `category()` is `BLOCK`). |
| `blocks()` | `boolean` | Whether the message should be dropped. |

### PlayerProfile

Record with fields: `uuid`, `name`, `names`, `ips`, `lastIp`, `clients`, `lastClient`, `protocol`, `referrer`, `firstJoin`, `lastSeen`, `joinCount`, `playtimeMs`, `online`, `punishments`. Timestamps are epoch milliseconds. List fields are never `null` but may be empty.

### MojangProfile and MojangStatus

`MojangProfile(UUID uuid, String name, MojangStatus status)`. When `status` is not `FOUND`, `uuid` and `name` are `null`.

`MojangStatus`: `FOUND` (resolved), `NOT_FOUND` (Mojang confirmed no such account), `UNKNOWN` (lookup could not be completed, for example a network error).

### DurationCheck

Record: `DurationCheck(boolean ok, long durationMillis, String error)`. When `ok`, `durationMillis` holds the possibly-capped duration to apply and `error` is `null`. When not `ok`, `error` explains the rejection.

### ScopeEntry

Record: `ScopeEntry(String key, Object value)`. One key-value pair from a store scope.

### CaptchaType and CaptchaOutcomeType

`CaptchaType`: `STANDARD` (a quick low-friction challenge), `DETAILED` (a stricter multi-step challenge).

`CaptchaOutcomeType`: `PASS`, `FAIL`, `TIMEOUT`.

## Listeners

### ModerationListener

Implement and register through `VeriteModeration.registerListener`. All methods are default no-ops, so override only what you need. Callbacks may run on the server main thread; do not block.

| Method | Fires when |
| --- | --- |
| `entryAdded(Punishment punishment)` | A punishment is issued. |
| `entryRemoved(Punishment punishment)` | A punishment is lifted, pardoned, or expired. |
| `broadcastSent(String message, String target)` | The moderation system sends a broadcast. |

### VanishListener

Implement and register through `VeriteVanish.registerListener`. Default no-ops; do not block in callbacks.

| Method | Fires when |
| --- | --- |
| `vanished(UUID player)` | A player enters vanish. |
| `unvanished(UUID player)` | A player leaves vanish. |