### BungeeCord LiteBansAPI Integration Example

Source: https://context7.com/ruany/litebansapi/llms.txt

This example demonstrates registering an event listener, overriding player targeting, and performing direct database queries using LiteBansAPI on BungeeCord. Database queries can be executed synchronously.

```java
import litebans.api.*;
import net.md_5.bungee.api.plugin.Plugin;

import java.sql.*;
import java.util.UUID;

public class BungeeMain extends Plugin {

    @Override
    public void onEnable() {
        // Register event listener
        Events.get().register(new Events.Listener() {
            @Override
            public void broadcastSent(String message, String type) {
                System.out.println("Broadcast [" + type + "]: " + message);
            }

            @Override
            public void entryAdded(Entry entry) {
                if ("ban".equals(entry.getType())) {
                    System.out.println("Ban added: " + entry);
                }
            }
        });

        // Override player targeting
        PlayerProvider.setInstance(new PlayerProvider() {
            @Override
            public String provide(String target) {
                getLogger().info("Resolving target: " + target);
                return target; // passthrough
            }
        });

        // Direct DB query (no async wrapper needed on BungeeCord)
        UUID uuid = UUID.fromString("b9b618bd-671c-303a-9900-ce0b3f6de348");
        System.out.println("Banned: " + Database.get().isPlayerBanned(uuid, null));

        // Raw SQL
        try (PreparedStatement st = Database.get() 
                .prepareStatement("SELECT COUNT(*) FROM {warnings} WHERE uuid=?")) {
            st.setString(1, uuid.toString());
            try (ResultSet rs = st.executeQuery()) {
                if (rs.next()) System.out.println("Warnings: " + rs.getLong(1));
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Gradle (Kotlin DSL) Dependency Setup for LiteBansAPI

Source: https://context7.com/ruany/litebansapi/llms.txt

Configure your Gradle project with the Kotlin DSL to include LiteBansAPI as a compile-only dependency. This method ensures that your plugin relies on the LiteBans plugin installed on the server at runtime, preventing version conflicts.

```kotlin
repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.gitlab.ruany", "LiteBansAPI", "0.6.1")
}
```

--------------------------------

### Gradle (Groovy DSL) Dependency Setup for LiteBansAPI

Source: https://context7.com/ruany/litebansapi/llms.txt

Set up your Gradle project using the Groovy DSL to add LiteBansAPI as a compile-only dependency. This approach ensures compatibility by depending on the LiteBans plugin present on the server at runtime.

```groovy
repositories {
    maven { url "https://jitpack.io" }
}

dependencies {
    compileOnly 'com.gitlab.ruany:LiteBansAPI:0.6.1'
}
```

--------------------------------

### Maven Dependency Setup for LiteBansAPI

Source: https://context7.com/ruany/litebansapi/llms.txt

Configure your Maven project to include LiteBansAPI as a compile-only dependency. This ensures the API is available at compile time but not bundled with your plugin, relying on the server's installed LiteBans plugin at runtime.

```xml
<repositories>
    <repository>
        <id>jitpack</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- LiteBansAPI – compileOnly: provided by the installed LiteBans plugin at runtime -->
    <dependency>
        <groupId>com.gitlab.ruany</groupId>
        <artifactId>LiteBansAPI</artifactId>
        <version>0.6.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

--------------------------------

### Get Events Instance

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Events.html

Retrieves the singleton instance of the Events class. This is the entry point for interacting with the event system.

```APIDOC
## get()

### Description
Retrieves the singleton instance of the Events class.

### Method
```
static Events
```

### Endpoint
```
Events.get()
```

### Response
#### Success Response (Events instance)
- **Events** (Events) - The singleton instance of the Events class.
```

--------------------------------

### Handle Missing LiteBans Implementation with MissingImplementationException

Source: https://context7.com/ruany/litebansapi/llms.txt

Catch MissingImplementationException when accessing LiteBans API singletons if LiteBans is not installed or enabled. Ensure LiteBans is listed as a dependency in your plugin configuration.

```java
import litebans.api.Database;
import litebans.api.exception.MissingImplementationException;

public class SafeChecker {

    public static boolean isBanned(java.util.UUID uuid) {
        try {
            return Database.get().isPlayerBanned(uuid, null);
        } catch (MissingImplementationException e) {
            // LiteBans not present – treat as "not banned" or log a warning
            System.err.println("LiteBans API not available: " + e.getMessage());
            return false;
        }
    }
}
```

```yaml
name: MyPlugin
version: 1.0
main: com.example.MyPlugin
depend: [LiteBans]   # Ensures LiteBans loads first; API will never be null
```

```yaml
name: MyPlugin
version: 1.0
main: com.example.BungeeMain
depends: [LiteBans]
```

--------------------------------

### MissingImplementationException Handling

Source: https://context7.com/ruany/litebansapi/llms.txt

The MissingImplementationException is thrown when the LiteBans API is accessed before LiteBans has been installed or enabled. It's recommended to declare LiteBans as a dependency in your plugin configuration to avoid this.

```APIDOC
## `MissingImplementationException`

Thrown by every `get()` singleton accessor when LiteBans is not installed or has not yet been enabled. Guard against it by declaring `depend: [LiteBans]` in your `plugin.yml` / `bungee.yml`.

### Handling the Exception
Wrap API calls in a try-catch block to gracefully handle situations where LiteBans might not be available.

### Example Usage
```java
import litebans.api.Database;
import litebans.api.exception.MissingImplementationException;

try {
    Database.get().isPlayerBanned(uuid, null);
} catch (MissingImplementationException e) {
    // LiteBans not present - handle accordingly
    System.err.println("LiteBans API not available: " + e.getMessage());
}
```

### Plugin Configuration
Ensure LiteBans is listed as a dependency in your plugin's configuration file:

**`plugin.yml` (Bukkit/Spigot)**
```yaml
depend: [LiteBans]
```

**`bungee.yml` (BungeeCord)**
```yaml
depends:
  - LiteBans
```
```

--------------------------------

### Get Kick by UUID, IP, or Server

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves an active kick entry based on player UUID, IP address, or server scope. Returns null if no active kick is found.

```java
@Nullable public abstract @Nullable Entry getKick(@Nullable UUID uuid, @Nullable String ip, @Nullable String server)
```

--------------------------------

### Get Kick by ID and Server

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves an active kick entry using its unique ID and server scope. Returns null if no active kick matches the ID.

```java
@Nullable public abstract @Nullable Entry getKick(long id, @Nullable String server)
```

--------------------------------

### Get RandomID Instance

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/RandomID.html

Retrieves a static instance of the RandomID class.

```APIDOC
## get()

### Description
Retrieves a static instance of the RandomID class.

### Method
`static RandomID`

### Endpoint
N/A (Java method call)

### Parameters
None

### Response
- **RandomID** (RandomID) - An instance of the RandomID class.
```

--------------------------------

### Get User UUIDs by IP Address

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Fetches a collection of player UUIDs associated with a given IP address. Useful for identifying multiple accounts linked to a single IP.

```java
public abstract Collection<UUID> getUsersByIP(String ip)
```

--------------------------------

### Get Player Name by UUID

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves the last recorded player name for a given UUID. Returns null if the player has never joined the server.

```java
@Nullable public abstract @Nullable String getPlayerName(@NonNull UUID uuid)
```

--------------------------------

### Database.get()

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves the singleton instance of the Database class. This is the entry point for all database operations.

```APIDOC
## Database.get()

### Description
Retrieves the singleton instance of the Database class. This is the entry point for all database operations.

### Method
`static`

### Endpoint
N/A (Java method call)

### Parameters
None

### Response
- **Database** (Database) - The singleton instance of the Database class.
```

--------------------------------

### PlayerProvider.provide

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/index-all.html

Provides player information. This method is always called asynchronously.

```APIDOC
## provide(String)

### Description
Provides player information. This method is always called asynchronously.

### Method
Method

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None specified
```

--------------------------------

### Count Player Warnings with Database#prepareStatement

Source: https://context7.com/ruany/litebansapi/llms.txt

Executes a raw SQL query to count all warnings for a given player UUID. Ensure the query is run asynchronously to avoid blocking the main server thread. Uses try-with-resources for proper resource management.

```java
import litebans.api.Database;
import org.bukkit.plugin.java.JavaPlugin;

import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class MyPlugin extends JavaPlugin {

    /** Count how many warnings a player has (all time, not just active). */
    public void countWarnings(String uuid) {
        getServer().getScheduler().runTaskAsynchronously(this, () -> {
            String sql = "SELECT COUNT(*) FROM {warnings} WHERE uuid=?";
            // Use try-with-resources to guarantee statement + result-set closure
            try (PreparedStatement st = Database.get().prepareStatement(sql)) {
                st.setString(1, uuid);
                try (ResultSet rs = st.executeQuery()) {
                    if (rs.next()) {
                        long count = rs.getLong(1);
                        System.out.println("Total warnings for " + uuid + ": " + count);
                        // Output: Total warnings for 5421d526-...: 3
                    }
                }
            } catch (SQLException e) {
                e.printStackTrace();
            }
        });
    }

    /** Fetch all active bans placed on a specific server scope. */
    public void listActiveBansOnServer(String serverScope) {
        getServer().getScheduler().runTaskAsynchronously(this, () -> {
            // {bans} is replaced with e.g. "litebans_bans" at runtime
            String sql = "SELECT id, uuid, reason FROM {bans} WHERE active=1 AND server_scope=?";
            try (PreparedStatement st = Database.get().prepareStatement(sql)) {
                st.setString(1, serverScope);
                try (ResultSet rs = st.executeQuery()) {
                    while (rs.next()) {
                        System.out.printf("ID=%d UUID=%s Reason=%s%n",
                                rs.getLong("id"),
                                rs.getString("uuid"),
                                rs.getString("reason"));
                    }
                }
            } catch (SQLException e) {
                e.printStackTrace();
            }
        });
    }
}
```

--------------------------------

### PlayerProvider.get()

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/PlayerProvider.html

Retrieves the PlayerProvider instance. This is a static method.

```APIDOC
## PlayerProvider.get()

### Description
Retrieves the PlayerProvider instance.

### Method
GET

### Endpoint
N/A (Static method)

### Parameters
None

### Response
#### Success Response (200)
- **PlayerProvider** (PlayerProvider) - The PlayerProvider instance.
```

--------------------------------

### PlayerProvider.provide(String target)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/PlayerProvider.html

This method is always called asynchronously. It allows overriding the targeted player argument in commands. The returned player does not need to be online. Return the original target if you want to leave it unmodified.

```APIDOC
## PlayerProvider.provide(String target)

### Description
Overrides the targeted player argument in commands. This method is called asynchronously.

### Method
POST (Conceptual, as it's an abstract method)

### Endpoint
N/A (Abstract method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **target** (String) - Required - The originally targeted player name.

### Request Example
```json
{
  "target": "PlayerName"
}
```

### Response
#### Success Response (200)
- **String** (String) - The new target, name or UUID or IP, not null.
```

--------------------------------

### MissingImplementationException Constructor

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/exception/MissingImplementationException.html

Initializes a new instance of the MissingImplementationException class.

```APIDOC
## MissingImplementationException Constructor

### Description
Initializes a new instance of the MissingImplementationException class.

### Method
public MissingImplementationException()

### Parameters
None
```

--------------------------------

### Entry Constructor

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Entry.html

The default constructor for the Entry class.

```APIDOC
## Entry Constructor

### Description

Public constructor for the Entry class.

### Method

`Entry()`

### Parameters

None
```

--------------------------------

### Prepare SQL Statement with Table Tokens

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Prepares a SQL statement for execution, automatically replacing LiteBans-specific tokens (e.g., {bans}, {mutes}) with their actual table names. This method throws SQLException.

```java
public abstract PreparedStatement prepareStatement(@NotNull String sql) throws SQLException
```

```java
try (PreparedStatement st = Database.get().prepareStatement("SELECT * FROM {bans}")) {

        try (ResultSet rs = st.executeQuery()) {

        ...

        }

        }
```

--------------------------------

### prepareStatement

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Prepares a SQL statement for execution.

```APIDOC
## prepareStatement

### Description
Prepares a SQL statement for execution. This is a lower-level database operation.

### Method
Not specified (likely a Java method call)

### Parameters
- **sql** (String) - Required - The SQL query string.

### Response
- **PreparedStatement** - Returns a PreparedStatement object ready for execution.
```

--------------------------------

### prepareStatement

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Prepares an SQL statement for execution, allowing for custom queries. Supports token replacement for table names.

```APIDOC
## prepareStatement

### Description
Prepares an SQL statement for execution, allowing for custom queries. Supports token replacement for table names.

### Method Signature
`public abstract PreparedStatement prepareStatement(@NotNull String sql) throws SQLException`

### Parameters
#### Path Parameters
- **sql** (String) - Required - SQL query. Tokens {bans}, {mutes}, {warnings}, {kicks}, {history}, {servers} will be replaced with real table names including the configured table prefix.

### Throws
- **SQLException** - If an SQL error occurs during statement preparation.

### Example
```java
try (PreparedStatement st = Database.get().prepareStatement("SELECT * FROM {bans}")) {
    try (ResultSet rs = st.executeQuery()) {
        // Process results
    }
}
```
```

--------------------------------

### PlayerProvider - Command Target Override

Source: https://context7.com/ruany/litebansapi/llms.txt

Intercept and transform player-name arguments before LiteBans processes punishment commands. Only one provider can be active.

```APIDOC
## PlayerProvider

### Description
Allows plugins to override the target player for punishment commands.

### Method
- `provide(String target)`: Called asynchronously to resolve the target player name.
  - **Parameters**:
    - `target` (String) - The raw player name argument provided in the command.
  - **Returns**:
    - (String) The resolved player name, UUID, or IP address.

### Usage Example
```java
import litebans.api.PlayerProvider;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.HashMap;
import java.util.Map;

public class MyPlugin extends JavaPlugin {

    private static final Map<String, String> ALIASES = new HashMap<>();
    static {
        ALIASES.put("god", "Notch");
        ALIASES.put("dev", "jeb_");
    }

    @Override
    public void onEnable() {
        PlayerProvider.setInstance(new PlayerProvider() {
            @Override
            public String provide(String target) {
                String resolved = ALIASES.getOrDefault(target.toLowerCase(), target);
                getLogger().info("PlayerProvider: '" + target + "' -> '" + resolved + "'");
                return resolved;
            }
        });
    }
}
```
```

--------------------------------

### Database.get()

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/class-use/Database.html

Retrieves an instance of the Database class. This is a static method provided for accessing the database connection.

```APIDOC
## Database.get()

### Description
Retrieves an instance of the Database class.

### Method
`static Database`

### Signature
`Database.get()`

### Returns
An instance of the `Database` class.
```

--------------------------------

### Methods Returning Entry

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/class-use/Entry.html

These methods in the litebans.api package return an Entry object, representing a ban, mute, warning, or kick record.

```APIDOC
## Database.getBan(long id, @Nullable String server)

### Description
Retrieves a ban entry by its ID and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **id** (long) - Required - The unique identifier of the ban.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The ban entry if found, otherwise null.
```

```APIDOC
## Database.getBan(UUID uuid, @Nullable String ip, @Nullable String server)

### Description
Retrieves a ban entry by UUID, IP address, and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The ban entry if found, otherwise null.
```

```APIDOC
## Database.getKick(long id, @Nullable String server)

### Description
Retrieves a kick entry by its ID and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **id** (long) - Required - The unique identifier of the kick.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The kick entry if found, otherwise null.
```

```APIDOC
## Database.getKick(UUID uuid, @Nullable String ip, @Nullable String server)

### Description
Retrieves a kick entry by UUID, IP address, and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The kick entry if found, otherwise null.
```

```APIDOC
## Database.getMute(long id, @Nullable String server)

### Description
Retrieves a mute entry by its ID and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **id** (long) - Required - The unique identifier of the mute.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The mute entry if found, otherwise null.
```

```APIDOC
## Database.getMute(UUID uuid, @Nullable String ip, @Nullable String server)

### Description
Retrieves a mute entry by UUID, IP address, and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The mute entry if found, otherwise null.
```

```APIDOC
## Database.getWarning(long id, @Nullable String server)

### Description
Retrieves a warning entry by its ID and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **id** (long) - Required - The unique identifier of the warning.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The warning entry if found, otherwise null.
```

```APIDOC
## Database.getWarning(UUID uuid, @Nullable String ip, @Nullable String server)

### Description
Retrieves a warning entry by UUID, IP address, and optionally by server.

### Method
`abstract @Nullable Entry`

### Parameters
#### Path Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
#### Success Response (Entry)
- **Entry** - The warning entry if found, otherwise null.
```

--------------------------------

### Database Methods

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/index-all.html

Methods for interacting with the LiteBans database, including retrieving mute and warning information, player status, and user data.

```APIDOC
## getMute(long, String)

### Description
Retrieves mute information.

### Method
Not specified (likely a Java method call).

### Parameters
- **long** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getMute(UUID, String, String)

### Description
Retrieves mute information using a UUID.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getPlayerName(UUID)

### Description
Retrieves a player's name using their UUID.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getUsersByIP(String)

### Description
Retrieves users associated with a given IP address.

### Method
Not specified (likely a Java method call).

### Parameters
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getWarning(long, String)

### Description
Retrieves warning information.

### Method
Not specified (likely a Java method call).

### Parameters
- **long** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getWarning(UUID, String, String)

### Description
Retrieves warning information using a UUID.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## isPlayerBanned(UUID, String)

### Description
Checks if a player is banned.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## isPlayerBanned(UUID, String, String)

### Description
Checks if a player is banned with additional criteria.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## isPlayerMuted(UUID, String)

### Description
Checks if a player is muted.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## isPlayerMuted(UUID, String, String)

### Description
Checks if a player is muted with additional criteria.

### Method
Not specified (likely a Java method call).

### Parameters
- **UUID** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.
- **String** (type unknown) - Description not available.

### Endpoint
N/A
```

--------------------------------

### Methods Accepting Entry

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/class-use/Entry.html

This method in the Events.Listener interface accepts an Entry object when a new entry is added to the database.

```APIDOC
## Events.Listener.entryAdded(Entry entry)

### Description
Called after an entry (ban, mute, warning, kick) is added to the database.

### Method
`void`

### Parameters
#### Path Parameters
- **entry** (Entry) - Required - The entry that was added to the database.
```

--------------------------------

### Events.register

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/index-all.html

Registers a listener for events.

```APIDOC
## register(Events.Listener)

### Description
Registers a listener for events.

### Method
Method

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None specified
```

--------------------------------

### Database.prepareStatement(String)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Prepares a SQL statement for execution. This method is intended for advanced users who need to execute custom queries.

```APIDOC
## Database.prepareStatement(String)

### Description
Prepares a SQL statement for execution. This method is intended for advanced users who need to execute custom queries.

### Method
`abstract`

### Endpoint
N/A (Java method call)

### Parameters
#### Path Parameters
- **sql** (String) - Required - The SQL query string to prepare.

### Response
#### Success Response (PreparedStatement)
- **PreparedStatement** - A prepared statement object that can be executed.
```

--------------------------------

### getWarning (by Player Info)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves warning information based on UUID, IP, or server.

```APIDOC
## getWarning (by Player Info)

### Description
Retrieves warning information for a player based on their UUID, IP address, or server.

### Method
Not specified (likely a Java method call)

### Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
- **boolean** - Returns a boolean indicating if a warning was found, or potentially details about the warning. (Note: The return type 'boolean' seems inconsistent with retrieving warning details.)
```

--------------------------------

### entryAdded

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Events.Listener.html

This event is triggered after a new entry (such as a ban, mute, warning, or kick) is successfully added to the LiteBans database.

```APIDOC
## entryAdded

### Description
Called after an entry (ban, mute, warning, kick) is added to the database.

### Method Signature
public void entryAdded(Entry entry)

### Parameters
#### Path Parameters
- **entry** (Entry) - Required - The entry object that was added.
```

--------------------------------

### Database.getWarning(UUID, String, String)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves the latest warning record for a player on a specific server.

```APIDOC
## Database.getWarning(UUID, String, String)

### Description
Retrieves the latest warning record for a player on a specific server.

### Method
`abstract`

### Endpoint
N/A (Java method call)

### Parameters
#### Path Parameters
- **uuid** (UUID) - Required - The unique identifier of the player.
- **ip** (String) - Required - The IP address of the player.
- **server** (String) - Optional - The name of the server to check. If null or empty, checks all servers.

### Response
#### Success Response (Entry)
- **Entry** - The latest warning record if found, otherwise null.
```

--------------------------------

### entryAdded Method

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Events.Listener.html

This method is invoked after a new entry (ban, mute, warning, kick) is added to the LiteBans database. It can be used to trigger actions based on new entries.

```APIDOC
## entryAdded Method

### Description
Called after an entry (ban, mute, warning, kick) is added to the database.

### Method Signature
`void entryAdded(Entry entry)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **entry** (Entry) - Required - The entry that was added to the database.
```

--------------------------------

### hasTemplate

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Entry.html

Checks if this entry was created using a template.

```APIDOC
## hasTemplate

### Description

Returns true if this entry was created with a template.

### Method

`hasTemplate()`

### Return Value

- `boolean`: True if a template was used, false otherwise.
```

--------------------------------

### hasTemplate

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Entry.html

Checks if this entry was created using a template.

```APIDOC
## hasTemplate

### Description
Returns true if this entry was created with a template.

### Method
`abstract boolean hasTemplate()`

### Return Value
- `boolean`: True if a template was used, false otherwise.
```

--------------------------------

### Database.getUsersByIP(String)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves a list of player UUIDs associated with a given IP address.

```APIDOC
## Database.getUsersByIP(String)

### Description
Retrieves a list of player UUIDs associated with a given IP address.

### Method
`abstract`

### Endpoint
N/A (Java method call)

### Parameters
#### Path Parameters
- **ip** (String) - Required - The IP address to query.

### Response
#### Success Response (List<UUID>)
- **List<UUID>** - A list of player UUIDs associated with the IP address.
```

--------------------------------

### getWarning(UUID uuid, String ip, String server)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves an active warning by player UUID or IP address, with optional server scope filtering.

```APIDOC
## getWarning(UUID uuid, String ip, String server)

### Description
Fetches an active warning record based on a player's UUID or IP address. Server scope can be specified to limit the search.

### Parameters
#### Path Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - Server scope to check. Can be null for global scope or Database.ANY_SERVER_SCOPE to check all scopes.

### Returns
An active warning entry corresponding to the provided UUID or IP, or null if none is found.
```

--------------------------------

### Events.register(Events.Listener listener)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/class-use/Events.Listener.html

Registers a listener to receive events. This is an abstract method, meaning its implementation is provided by the concrete classes that extend or implement the Events class.

```APIDOC
## Events.register(Events.Listener listener)

### Description
Registers a listener to receive events. This method is abstract and requires implementation by concrete event handling classes.

### Method
`abstract void`

### Parameters
#### Path Parameters
- **listener** (Events.Listener) - Required - The listener object to register.
```

--------------------------------

### getMute (by Player Info)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves mute information based on UUID, IP, or server.

```APIDOC
## getMute (by Player Info)

### Description
Retrieves mute information for a player based on their UUID, IP address, or server.

### Method
Not specified (likely a Java method call)

### Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
- **String** - Returns a String representing mute details, or null if not found.
```

--------------------------------

### Database.getWarning(long, String)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves a warning record by its ID for a specific server.

```APIDOC
## Database.getWarning(long, String)

### Description
Retrieves a warning record by its ID for a specific server.

### Method
`abstract`

### Endpoint
N/A (Java method call)

### Parameters
#### Path Parameters
- **id** (long) - Required - The unique identifier of the warning record.
- **server** (String) - Optional - The name of the server to check. If null or empty, checks all servers.

### Response
#### Success Response (Entry)
- **Entry** - The warning record if found, otherwise null.
```

--------------------------------

### Register LiteBans Event Listener

Source: https://context7.com/ruany/litebansapi/llms.txt

Implement and register a listener to react to LiteBans punishment events. Callbacks are asynchronous; use Bukkit.getScheduler() for main thread interactions. Ensure unregistration in onDisable to prevent memory leaks.

```java
import litebans.api.Entry;
import litebans.api.Events;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    private Events.Listener litebansListener;

    @Override
    public void onEnable() {
        litebansListener = new Events.Listener() {

            /** Fired after a LiteBans broadcast message is sent to permitted players. */
            @Override
            public void broadcastSent(String message, String type) {
                // type may be null; if non-null, viewers need "litebans.notify.[type]"
                getLogger().info("[Broadcast type=" + type + "] " + message);
                // Example: [Broadcast type=ban] §cNotch has been banned: Hacking
            }

            /** Fired after any entry (ban/mute/warn/kick) is written to the database. */
            @Override
            public void entryAdded(Entry entry) {
                // This fires only on the local plugin instance, not across the network
                switch (entry.getType()) {
                    case "ban":
                        getLogger().warning("New BAN: " + entry.getUuid()
                                + " by " + entry.getExecutorName()
                                + " – " + entry.getReason());
                        // Run follow-up work back on the main thread if needed:
                        Bukkit.getScheduler().runTask(MyPlugin.this, () ->
                            Bukkit.broadcastMessage("§4" + entry.getExecutorName()
                                + " banned a player!"));
                        break;
                    case "mute":
                        getLogger().info("New MUTE: " + entry.getUuid());
                        break;
                    case "warn":
                        getLogger().info("New WARNING #" + entry.getId());
                        break;
                    case "kick":
                        getLogger().info("New KICK: " + entry.getUuid());
                        break;
                }
            }

            /** Fired after an entry is removed (unbanned, unmuted, etc.). */
            @Override
            public void entryRemoved(Entry entry) {
                getLogger().info("Entry removed: [" + entry.getType() + " #" + entry.getId()
                        + "] removed by " + entry.getRemovedByName()
                        + " reason: " + entry.getRemovalReason());
                // Note: wildcard unbans (/staffrollback) do NOT fire this event per entry
            }
        };

        Events.get().register(litebansListener);
    }

    @Override
    public void onDisable() {
        // Always unregister to avoid memory leaks
        if (litebansListener != null) {
            Events.get().unregister(litebansListener);
        }
    }
}
```

--------------------------------

### Override Player Name Resolution

Source: https://context7.com/ruany/litebansapi/llms.txt

Implement and set a PlayerProvider to intercept and transform player names before LiteBans processes a punishment command. The provide method must return non-null and is called asynchronously. Only one provider can be active at a time.

```java
import litebans.api.PlayerProvider;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.HashMap;
import java.util.Map;

public class MyPlugin extends JavaPlugin {

    // Example: resolve display names or aliases to real player names
    private static final Map<String, String> ALIASES = new HashMap<>();
    static {
        ALIASES.put("god", "Notch");
        ALIASES.put("dev", "jeb_");
    }

    @Override
    public void onEnable() {
        PlayerProvider.setInstance(new PlayerProvider() {
            @Override
            public String provide(String target) {
                // target is the raw argument typed in the command, e.g. "/ban god"
                String resolved = ALIASES.getOrDefault(target.toLowerCase(), target);
                getLogger().info("PlayerProvider: '" + target + "' -> '" + resolved + "'");
                // Returning the original `target` leaves behaviour unchanged.
                // Returning a UUID string or IP address redirects the punishment.
                return resolved;
                // If target was "god", LiteBans will now ban "Notch" instead.
            }
        });
    }
}
```

--------------------------------

### Convert Numeric IDs to Obfuscated Strings with RandomID

Source: https://context7.com/ruany/litebansapi/llms.txt

Use RandomID.get().convert() to transform numeric database IDs into short, obfuscated strings for public display. This prevents leaking sequential database IDs. The conversion is performed asynchronously.

```java
import litebans.api.RandomID;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getServer().getScheduler().runTaskAsynchronously(this, () -> {

            // --- convert: numeric ID  →  random string ---
            long numericID = 101L;
            String randomID = RandomID.get().convert(numericID);
            System.out.println("Random ID for ban #101: " + randomID);
            // Example output: "Random ID for ban #101: X7kP2m"

            // --- reveal: random string  →  numeric ID ---
            long revealed = RandomID.get().reveal(randomID);
            if (revealed == RandomID.RESULT_ERROR) {
                System.out.println("Invalid random ID provided.");
            } else {
                System.out.println("Numeric ID: " + revealed); // 101
            }

            // --- Typical appeal-form use case ---
            // Player submits appeal with random ID "X7kP2m"
            String appealID = "X7kP2m";
            long dbID = RandomID.get().reveal(appealID);
            if (dbID != RandomID.RESULT_ERROR) {
                // Now look up the actual entry
                litebans.api.Entry entry = litebans.api.Database.get()
                        .getBan(dbID, litebans.api.Database.ANY_SERVER_SCOPE);
                if (entry != null) {
                    System.out.println("Appeal for ban on: " + entry.getUuid()
                            + " reason: " + entry.getReason());
                }
            }
        });
    }
}
```

--------------------------------

### getWarning (by ID)

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves warning information using a warning ID and server.

```APIDOC
## getWarning (by ID)

### Description
Retrieves warning information using a specific warning ID and the server identifier.

### Method
Not specified (likely a Java method call)

### Parameters
- **id** (long) - Required - The ID of the warning.
- **server** (String) - Optional - The server identifier.

### Response
- **Entry** - Returns an Entry object containing warning details, or null if not found.
```

--------------------------------

### getKick

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/litebans/api/Database.html

Retrieves kick information based on UUID, IP, or server.

```APIDOC
## getKick

### Description
Retrieves kick information. This method can be called with a player's UUID, IP address, or server identifier.

### Method
Not specified (likely a Java method call)

### Parameters
- **uuid** (UUID) - Optional - The UUID of the player.
- **ip** (String) - Optional - The IP address of the player.
- **server** (String) - Optional - The server identifier.

### Response
- **Entry** - Returns an Entry object containing kick details, or null if not found.
```

--------------------------------

### Entry Methods

Source: https://gitlab.com/ruany/litebansapi/-/blob/master/public/index-all.html

Methods related to LiteBans entries, providing information about their expiration, templates, and unique identifiers.

```APIDOC
## getRandomID()

### Description
Returns the random ID of this entry.

### Method
Not specified (likely a Java method call).

### Parameters
None.

### Endpoint
N/A
```

```APIDOC
## getRemainingDuration(long)

### Description
Returns the amount of milliseconds until this entry expires.

### Method
Not specified (likely a Java method call).

### Parameters
- **long** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getRemainingDurationString(long)

### Description
Returns a string representing the amount of time until this entry expires.

### Method
Not specified (likely a Java method call).

### Parameters
- **long** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## getTemplateID()

### Description
Returns the ID of the template used to create this entry.

### Method
Not specified (likely a Java method call).

### Parameters
None.

### Endpoint
N/A
```

```APIDOC
## getTemplateName()

### Description
Returns the name of the template which was used to create this entry, or a blank string if none was used.

### Method
Not specified (likely a Java method call).

### Parameters
None.

### Endpoint
N/A
```

```APIDOC
## hasTemplate()

### Description
Returns true if this entry was created with a template.

### Method
Not specified (likely a Java method call).

### Parameters
None.

### Endpoint
N/A
```

```APIDOC
## isExpired(long)

### Description
Returns true if this entry has expired, false otherwise.

### Method
Not specified (likely a Java method call).

### Parameters
- **long** (type unknown) - Description not available.

### Endpoint
N/A
```

```APIDOC
## isPermanent()

### Description
Returns true if this entry does not have an expiration date.

### Method
Not specified (likely a Java method call).

### Parameters
None.

### Endpoint
N/A
```

--------------------------------

### Retrieving Punishment Entry by UUID and IP

Source: https://context7.com/ruany/litebansapi/llms.txt

Retrieve a specific punishment entry (ban, mute, warning, kick) using player UUID and IP address, with server scope filtering.

```APIDOC
## Retrieving Punishment Entry by UUID and IP

### Description
Retrieve a specific punishment entry (ban, mute, warning, kick) using player UUID and IP address, with server scope filtering.

### Method
`Database.get().getBan(UUID playerUUID, String ipAddress, String serverScope)`
`Database.get().getMute(UUID playerUUID, String ipAddress, String serverScope)`
`Database.get().getWarning(UUID playerUUID, String ipAddress, String serverScope)`
`Database.get().getKick(UUID playerUUID, String ipAddress, String serverScope)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
Entry activeBan = Database.get().getBan(playerUUID, null, Database.ANY_SERVER_SCOPE);
if (activeBan != null) {
    System.out.println("Ban reason: "   + activeBan.getReason());
    System.out.println("Banned by: "    + activeBan.getExecutorName());
    System.out.println("Expires in ms: " + activeBan.getRemainingDuration(System.currentTimeMillis()));
    System.out.println("Permanent: "    + activeBan.isPermanent());
    System.out.println("Server scope: " + activeBan.getServerScope());
    System.out.println("Random ID: "    + activeBan.getRandomID());
}
```

### Response
#### Success Response (200)
- **Entry** - An Entry object representing the punishment, or null if no matching entry is found.
  - **reason** (string) - The reason for the punishment.
  - **executorName** (string) - The name of the executor.
  - **remainingDuration** (long) - Remaining duration in milliseconds.
  - **isPermanent** (boolean) - True if the punishment is permanent.
  - **serverScope** (string) - The server scope of the punishment.
  - **randomID** (string) - The random ID of the entry.
  - **type** (string) - The type of entry (e.g., "ban", "mute").

#### Response Example
```
// Example output if an active ban is found
System.out.println("Ban reason: "   + activeBan.getReason());
System.out.println("Banned by: "    + activeBan.getExecutorName());
```
```