# Developer API Integration Guide

This guide explains how to compile against and integrate with the **peyajAuth** API and custom events.

Since peyajAuth is obfuscated for security, we explicitly protect the API package and event classes from name scrambling. You can compile your custom plugins against it by using your compiled `peyajAuth.jar` as a local project dependency.

---

## Step 1: Add the Dependency

Place the `peyajAuth.jar` into your project's `libs` directory and configure your build tool:

### Gradle Kotlin DSL (`build.gradle.kts`):
```kotlin
repositories {
    flatDir {
        dirs("libs")
    }
}

dependencies {
    compileOnly(files("libs/peyajAuth.jar"))
}
```

### Maven (`pom.xml`):
```xml
<dependency>
    <groupId>me.peyaj</groupId>
    <artifactId>peyajauth</artifactId>
    <version>1.4</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/peyajAuth.jar</systemPath>
</dependency>
```

---

## Step 2: Declare Dependency in `plugin.yml`

To ensure your plugin loads after peyajAuth, add the following to your `plugin.yml`:
```yaml
depend: [peyajAuth]
```

---

## Step 3: Accessing the API

All interactions are coordinated through the `PeyajAuthAPI` interface. You can fetch the singleton provider instance at runtime using:

```java
import me.peyaj.peyajauth.api.PeyajAuthAPI;

PeyajAuthAPI api = PeyajAuthAPI.getInstance();
```

---

## API Methods Reference

### 1. `isAuthenticated(Player player)`
* **Description**: Checks if a player has successfully completed the login/registration process.
* **Return Type**: `boolean`
* **Example**:
```java
if (!api.isAuthenticated(player)) {
    player.sendMessage("You must log in first!");
}
```

### 2. `isPremium(Player player)`
* **Description**: Checks if the player has been authenticated as a verified premium Mojang/Xbox Live account (Java premium auto-login or Bedrock Floodgate bypass).
* **Return Type**: `boolean`
* **Example**:
```java
if (api.isPremium(player)) {
    player.sendMessage("Welcome verified premium player!");
}
```

### 3. `login(Player player)` / `forceLogin(Player player)`
* **Description**: Force-authenticates a player, bypassing any password entry prompts and clearing their restrictions.
* **Return Type**: `void`
* **Example**:
```java
api.login(player); // Player is now marked as authenticated
```

### 4. `logout(Player player)`
* **Description**: De-authenticates an active player session and places them back into the restricted state (prompting for login).
* **Return Type**: `void`
* **Example**:
```java
api.logout(player);
```

### 5. `register(Player player, String password)`
* **Description**: Registers a new account for the player with the specified password, automatically logging them in.
* **Return Type**: `void`
* **Example**:
```java
api.register(player, "mySecurePassword123");
```

### 6. `unregister(Player player)`
* **Description**: Deletes the player's registration account from the database and logs them out.
* **Return Type**: `void`
* **Example**:
```java
api.unregister(player);
```

---

## Custom Events Reference

You can listen to state changes by creating a standard Bukkit listener for peyajAuth's custom events. All custom events inherit from `org.bukkit.event.player.PlayerEvent`.

### List of Custom Events

| Event Class | Description |
| :--- | :--- |
| `PlayerAuthenticateEvent` | Fired when a player is successfully authenticated (logs in). |
| `PlayerFailedLoginEvent` | Fired when a player inputs an incorrect password. |
| `PlayerRegisterEvent` | Fired when a player registers a new account successfully. |
| `PlayerLogoutEvent` | Fired when a player logs out of their session. |
| `PlayerPasswordChangeEvent` | Fired when a player successfully changes their password. |
| `PlayerPremiumLoginEvent` | Fired when a premium Java/Bedrock player auto-authenticates. |

### Listener Example

Here is a full example of a custom Bukkit listener implementing the events:

```java
import me.peyaj.peyajauth.event.PlayerAuthenticateEvent;
import me.peyaj.peyajauth.event.PlayerFailedLoginEvent;
import me.peyaj.peyajauth.event.PlayerRegisterEvent;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class AuthListener implements Listener {

    @EventHandler
    public void onPlayerLogin(PlayerAuthenticateEvent event) {
        Player player = event.getPlayer();
        Bukkit.getLogger().info(player.getName() + " has completed login!");
    }

    @EventHandler
    public void onPlayerFailed(PlayerFailedLoginEvent event) {
        Player player = event.getPlayer();
        Bukkit.getLogger().warning(player.getName() + " failed a login attempt!");
    }

    @EventHandler
    public void onPlayerRegister(PlayerRegisterEvent event) {
        Player player = event.getPlayer();
        player.sendMessage("Thank you for registering on our server!");
    }
}
```