# oyeOwner Integration Guide for AI Assistants

This document provides concise instructions for integrating the **oyeOwner** API into other Bukkit/Spigot plugins.

## 1. Dependency Configuration (Maven)
Add the `oyeOwner` project as a dependency in your `pom.xml`.

```xml
<dependency>
    <groupId>party.cybsec</groupId>
    <artifactId>oyeOwner</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

## 2. Plugin Configuration (plugin.yml)
Add `oyeOwner` as a dependency to ensure it loads before your plugin.

```yaml
depend: [oyeOwner]
```

## 3. Java API Usage

### Accessing the API
The API is accessible via a static getter in the main class: `party.cybsec.OyeOwner.getAPI()`.

### Sync Lookup (Blocking)
Use this if you are already in an asynchronous task or if a tiny delay is acceptable.
```java
import org.bukkit.block.Block;
import party.cybsec.OyeOwner;

// Returns String username or null
String owner = OyeOwner.getAPI().getBlockOwner(block);
```

### Async Lookup (Non-blocking)
Recommended for use on the main thread to avoid lag.
```java
import org.bukkit.block.Block;
import party.cybsec.OyeOwner;

OyeOwner.getAPI().getBlockOwnerAsync(block).thenAccept(owner -> {
    if (owner != null) {
        // Player name found: owner
    } else {
        // No ownership data found
    }
});
```

## 4. Summary of Capabilities
- **Lookback Period**: 60 days.
- **Action Tracked**: Block Placement (Action ID 1).
- **Core Engine**: Powered by CoreProtect with a reflection-based safe hook.