Add Portals API documentation

Author: NonSwag

content/docs/portals/api/events.mdx

@@ -0,0 +1,94 @@
+---
+title: Events
+description: Custom events to hook into portal interactions.
+---
+
+Portals provides custom events that allow developers to hook into portal interactions.
+
+## Portal Entry Events
+
+These events are fired when entities interact with portals.
+
+### PreEntityPortalEnterEvent
+
+Fired before an entity enters a portal and before any checks are performed.  
+Checks include permission, cooldown, and entry cost.  
+Canceling this event will prevent the entity from entering and using the portal.
+
+```java
+@EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
+public void onPrePortalEnter(PreEntityPortalEnterEvent event) {
+    Portal portal = event.getPortal();
+    Entity entity = event.getEntity();
+
+    // Prevent certain entities from using portals
+    if (entity.getType() == EntityType.CREEPER) {
+        event.setCancelled(true);
+    }
+}
+```
+
+### EntityPortalEnterEvent
+
+Fired when an entity enters a portal and all checks have succeeded.  
+Checks include permission, cooldown, and entry cost.  
+Canceling this event will prevent the entity from entering and using the portal.
+
+```java
+@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
+public void onPortalEnter(EntityPortalEnterEvent event) {
+    Portal portal = event.getPortal();
+    Entity entity = event.getEntity();
+
+    entity.sendMessage("Entering portal: " + portal.getName());
+}
+```
+
+### EntityPortalExitEvent
+
+Fired when an entity exits a portal.
+
+```java
+@EventHandler(priority = EventPriority.MONITOR)
+public void onPortalExit(EntityPortalExitEvent event) {
+    Portal portal = event.getPortal();
+    Entity entity = event.getEntity();
+
+    entity.sendMessage("You left the portal: " + portal.getName());
+}
+```
+
+## Warmup Events
+
+Warmup events are fired when portals have a warmup duration configured.  
+These events allow you to track and modify warmup behavior.
+
+### EntityPortalWarmupEvent
+
+Fired when an entity enters a portal and begins the warmup period.
+
+```java
+@EventHandler(priority = EventPriority.MONITOR)
+public void onWarmupStart(EntityPortalWarmupEvent event) {
+    Portal portal = event.getPortal();
+    Entity entity = event.getEntity();
+    Duration warmup = event.getWarmup();
+
+    entity.sendMessage("Stay in the portal for " + warmup.getSeconds() + " seconds…");
+}
+```
+
+### EntityPortalWarmupCancelEvent
+
+Fired when a entity leaves the portal before the warmup completes, cancelling the pending action.
+
+```java
+@EventHandler(priority = EventPriority.MONITOR)
+public void onWarmupCancel(EntityPortalWarmupCancelEvent event) {
+    Portal portal = event.getPortal();
+    Entity entity = event.getEntity();
+    Duration remaining = event.getRemaining();
+
+    entity.sendMessage("You left the portal " + remaining.getSeconds() + " seconds early!");
+}
+```

content/docs/portals/api/index.mdx

@@ -0,0 +1,70 @@
+---
+title: API
+description: API documentation for the Portals plugin.
+---
+
+import { latestVersion } from "@/lib/api"
+export const version = await latestVersion("portals")
+export const javadocs = `https://repo.thenextlvl.net/javadoc/releases/net/thenextlvl/portals/${version}`
+
+Javadocs for the API can be found <a href={javadocs} target="_blank">here</a>.
+
+## Getting Started
+
+### PortalProvider
+
+The `PortalProvider` is the main interface for interacting with portals.  
+You can retrieve an instance using:
+
+```java
+PortalProvider provider = PortalProvider.provider();
+```
+
+The provider offers methods to manage portals:
+
+```java
+// Create a new portal
+Portal portal = provider.createPortal("my-portal", boundingBox);
+
+// Delete a portal
+provider.deletePortal(portal);
+
+// Get a portal by name
+Optional<Portal> portal = provider.getPortal("my-portal");
+
+// Get all portals
+Stream<Portal> portals = provider.getPortals();
+```
+
+### PortalConfig
+
+The `PortalConfig` provides a view of the plugin configuration.  
+You can retrieve an instance using:
+
+```java
+PortalConfig config = PortalConfig.config();
+```
+
+### BoundingBox
+
+A `BoundingBox` defines the physical region of a portal.  
+You can create one using:
+
+```java
+BoundingBox box = BoundingBox.of(world, minPosition, maxPosition);
+```
+
+### SelectionProvider
+
+The `SelectionProvider` provides selection functionality for players (e.g., WorldEdit selections).  
+It can also be extended to provide your own custom selection provider.
+
+An instance can be obtained via the Bukkit services manager if one is available:
+
+```java
+SelectionProvider selection = Bukkit.getServicesManager().load(SelectionProvider.class);
+if (selection != null) {
+    // Selection provider is available (e.g., WorldEdit is installed)
+    Optional<BoundingBox> box = selection.getSelection(player);
+}
+```

content/docs/portals/meta.json

@@ -19,7 +19,8 @@
 		"permissions",
 		"configuration",
 		"---For Developers---",
-		"api/repository",
-		"api/index"
+		"repository",
+		"api/index",
+		"api/events"
 	]
 }

content/docs/portals/api/repository.mdx content/docs/portals/repository.mdxcontent/docs/portals/api/repository.mdx renamed to content/docs/portals/repository.mdx

@@ -5,7 +5,7 @@ description: Add the Portals API to your project
 
 import { Tab, Tabs } from "fumadocs-ui/components/tabs"
 import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock"
-import { latestVersion } from "@/lib/api"
+import { latestVersion } from "@/lib/api.ts"
 export const version = await latestVersion("portals")
 
 ## Add our Repository