Feat/convenience helpers

CHANGELOG.md

@@ -3,6 +3,45 @@
 All notable changes to TeamsAPI are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [2.5.0]
+
+Non-breaking additions. No changes required for existing providers or consumers.
+
+### Added
+
+#### Convenience methods
+
+- `TeamsService.getTeamIds()` - returns all team UUIDs for iteration without
+  loading full team objects.
+- `Team.getOwner()` - default method returning the owner's `TeamMember` record.
+- `VelocityTeam.getMemberUUIDs()` - returns UUIDs of all members.
+- `VelocityTeam.getOwner()` - default method returning the owner's record.
+
+#### Role prefix reset
+
+New `resetPrefixOverride()` method on both `TeamRole` and `TeamRoleDefinition`
+clears any active prefix override, restoring the built-in default:
+
+```java
+TeamRole.OWNER.setPrefixOverride("[Lord]");
+TeamRole.OWNER.resetPrefixOverride(); // back to "Owner"
+```
+
+Equivalent to calling `setPrefixOverride(null)`.
+
+- `TeamsAPI.API_VERSION` updated to `2.5.0`.
+
+### Changed
+
+- `docs/api.md` Team lookup section now correctly lists `getTeam`, `getTeamByName`,
+  and `getPlayerTeam` alongside `getAllTeams`, `getTeamCount`, and `getTeamIds`.
+- `docs/velocity.md` updated to document `getMemberUUIDs()` and `getOwner()` on
+  `VelocityTeam`.
+
+### Migration
+
+No behavioural changes for existing providers or consumers.
+
 ## [2.4.0]
 
 Non-breaking additions. No changes required for existing providers or consumers.

docs/api.md

@@ -145,11 +145,12 @@ Implemented by team plugins. Obtained via `TeamsAPI.getService()`.
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getTeam(teamId)` | `Optional<Team>` | Finds a team by UUID. |
-| `getTeamByName(name)` | `Optional<Team>` | Finds a team by name (case-insensitive where possible). |
-| `getPlayerTeam(playerUUID)` | `Optional<Team>` | Returns the team the player belongs to. |
+| `getTeam(teamId)` | `Optional<Team>` | Retrieves a team by its unique ID. |
+| `getTeamByName(name)` | `Optional<Team>` | Retrieves a team by name (case-insensitive where possible). |
+| `getPlayerTeam(playerUUID)` | `Optional<Team>` | The team the given player belongs to. |
 | `getAllTeams()` | `Collection<Team>` | All registered teams. |
 | `getTeamCount()` | `int` | Total number of teams. |
+| `getTeamIds()` | `Collection<UUID>` | All team UUIDs (convenience). |
 
 ### Membership management
 
@@ -363,6 +364,7 @@ A read-only snapshot of a team. Obtain via `TeamsService` lookup methods.
 | `getMember(playerUUID)` | `Optional<TeamMember>` | The member record for the given player. |
 | `isMember(playerUUID)` | `boolean` | Whether the player is a member (any role). |
 | `isOwner(playerUUID)` | `boolean` | Whether the player holds the OWNER role. |
+| `getOwner()` | `Optional<TeamMember>` | Convenience: owner's member record. |
 
 ## `TeamMember` (interface)
 
@@ -496,6 +498,7 @@ Helper methods:
 | `getPrefix()` | Effective display prefix - returns the consumer-supplied override if one is set, otherwise the compile-time default. |
 | `getDefaultPrefix()` | Compile-time default prefix. Always `"Owner"`, `"Admin"`, or `"Member"` regardless of any active override. |
 | `setPrefixOverride(prefix)` | Sets or clears (if `null`) a JVM-wide prefix override for this constant. |
+| `resetPrefixOverride()` | Clears any prefix override on this role, restoring the built-in default. |
 | `applyPrefixes(prefixes)` | Static. Applies prefix overrides from a `Map<TeamRole, String>`. A `null` value in the map clears that role's override; `null` keys are silently skipped. |
 | `resetAllPrefixes()` | Static. Clears prefix overrides on every built-in role constant. |
 | `outranks(other)` | Returns `true` if this role has a higher priority than `other`. |
@@ -516,6 +519,7 @@ Used with the custom role registry on `TeamsAPI` to publish roles beyond the thr
 | `getPrefix()` | Effective prefix - returns the override if set, otherwise the default. |
 | `getDefaultPrefix()` | Compile-time default prefix; unaffected by `setPrefixOverride`. |
 | `setPrefixOverride(String)` | Sets or clears (`null`) a prefix override for this definition. |
+| `resetPrefixOverride()` | Clears any prefix override on this role, restoring the built-in default. |
 | `outranks(other)` | Returns `true` if this definition has higher priority than `other`. |
 | `canManage(target)` | Returns `true` if this definition can manage the `target` role. |
 | `of(TeamRole)` | Static factory. Creates a `TeamRoleDefinition` mirroring a built-in role (key = lower-case name). |
@@ -605,11 +609,17 @@ Non-breaking additions. No changes required for existing providers or consumers.
   prefix override for the role constant.
 - New `TeamRole.applyPrefixes(Map<TeamRole, String>)`: bulk-sets overrides from a map.
 - New `TeamRole.resetAllPrefixes()`: clears overrides on every built-in role constant.
+- New `TeamRole.resetPrefixOverride()`: clears override on a single role constant.
 - New `TeamRoleDefinition` class: custom role definitions with key, priority, and prefix.
+- New `TeamRoleDefinition.resetPrefixOverride()`: clears override on a role definition.
 - New `TeamsAPI` registry methods: `registerCustomRole`, `unregisterCustomRole`,
   `getCustomRole`, `getCustomRoles`, `isCustomRoleRegistered`.
+- New `TeamsService.getTeamIds()`: convenience method returning all team UUIDs.
+- New `Team.getOwner()`: convenience default method returning owner's member record.
 - New `TeamMember.getRoleDefinition()` default method: wraps the member's `TeamRole`
   in a `TeamRoleDefinition`. Providers with custom roles should override this.
+- New `VelocityTeam.getOwner()`: convenience default method returning owner's member record.
+- New `VelocityTeam.getMemberUUIDs()`: returns UUIDs of all team members.
 
 ### 2.3.0
 

docs/velocity.md

@@ -198,12 +198,12 @@ All methods return `CompletableFuture<T>` and may complete exceptionally with
 | `getPlayerTeam(playerUUID)` | `CompletableFuture<Optional<VelocityTeam>>` | The team the player belongs to, if any. |
 | `getTeam(teamId)` | `CompletableFuture<Optional<VelocityTeam>>` | Finds a team by UUID. |
 | `getTeamByName(name)` | `CompletableFuture<Optional<VelocityTeam>>` | Finds a team by name. |
+| `getAllTeams()` | `CompletableFuture<Collection<VelocityTeam>>` | All teams registered on the backend. |
 | `getTeamCount()` | `CompletableFuture<Integer>` | Total number of teams on the backend. |
 | `teamExists(name)` | `CompletableFuture<Boolean>` | Whether a team with that name exists. |
 | `isMember(teamId, playerUUID)` | `CompletableFuture<Boolean>` | Whether the player is a member of the team. |
 | `getMemberRole(teamId, playerUUID)` | `CompletableFuture<Optional<VelocityTeamRole>>` | The player's role within the team, if a member. |
 | `getMemberInfo(teamId, playerUUID)` | `CompletableFuture<Optional<VelocityTeamMember>>` | The player's full membership record, if a member. |
-| `getAllTeams()` | `CompletableFuture<Collection<VelocityTeam>>` | All teams registered on the backend. |
 
 ### `VelocityTeam` (interface)
 
@@ -215,6 +215,11 @@ All methods return `CompletableFuture<T>` and may complete exceptionally with
 | `getOwnerUUID()` | `UUID` | UUID of the team owner. |
 | `getSize()` | `int` | Current member count. |
 | `getMaxSize()` | `int` | Maximum member cap; `-1` means unlimited. |
+| `getMembers()` | `Collection<VelocityTeamMember>` | All members, may be empty if not included in response. |
+| `getMemberUUIDs()` | `Collection<UUID>` | UUIDs of all members. |
+| `isMember(playerUUID)` | `boolean` | Whether the player is a member. |
+| `isOwner(playerUUID)` | `boolean` | Whether the player is the owner. |
+| `getOwner()` | `Optional<VelocityTeamMember>` | Convenience: owner's member record. |
 
 ### `VelocityTeamMember` (interface)
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.github.ez-plugins</groupId>
     <artifactId>teams-api-parent</artifactId>
-    <version>2.4.0</version>
+    <version>2.5.0</version>
     <packaging>pom</packaging>
     <name>TeamsAPI Parent</name>
     <description>Universal Teams API for Minecraft: bridges team plugins with a clean, timeless interface.</description>

teams-api-bungeecord/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-extension-betterteams/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-extension-betterteams/src/main/java/com/skyblockexp/teamsapi/extension/betterteams/BetterTeamsServiceAdapter.java

@@ -101,7 +101,13 @@ public Collection<com.skyblockexp.teamsapi.model.Team> getAllTeams() {
 
     @Override
     public int getTeamCount() {
-        return getAllTeams().size();
+        return Team.getTeamManager().getLoadedTeamListClone().size();
+    }
+
+    @Override
+    public Collection<UUID> getTeamIds() {
+        final Map<UUID, Team> loaded = Team.getTeamManager().getLoadedTeamListClone();
+        return Collections.unmodifiableCollection(new ArrayList<>(loaded.keySet()));
     }
 
     @Override

teams-api-extension-kingdomsx/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-extension-kingdomsx/src/main/java/com/skyblockexp/teamsapi/extension/kingdomsx/KingdomsXServiceAdapter.java

@@ -104,6 +104,17 @@ public int getTeamCount() {
         return Kingdoms.get().getDataCenter().getKingdomManager().getKingdoms().size();
     }
 
+    @Override
+    public Collection<UUID> getTeamIds() {
+        final Collection<Kingdom> kingdoms =
+                Kingdoms.get().getDataCenter().getKingdomManager().getKingdoms();
+        final Collection<UUID> ids = new ArrayList<>(kingdoms.size());
+        for (final Kingdom kingdom : kingdoms) {
+            ids.add(kingdom.getId());
+        }
+        return Collections.unmodifiableCollection(ids);
+    }
+
     @Override
     public boolean addMember(final UUID teamId, final UUID playerUUID, final TeamRole role) {
         if (teamId == null || playerUUID == null || role == null) {

teams-api-extension-towny/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-extension-towny/src/main/java/com/skyblockexp/teamsapi/extension/towny/TownyServiceAdapter.java

@@ -138,6 +138,16 @@ public int getTeamCount() {
         return getAllTeams().size();
     }
 
+    @Override
+    public Collection<UUID> getTeamIds() {
+        final Collection<Team> teams = getAllTeams();
+        final Collection<UUID> ids = new ArrayList<>(teams.size());
+        for (final Team team : teams) {
+            ids.add(team.getId());
+        }
+        return Collections.unmodifiableCollection(ids);
+    }
+
     @Override
     public boolean addMember(final UUID teamId, final UUID playerUUID, final TeamRole role) {
         if (teamId == null || playerUUID == null || role == null) {
@@ -327,4 +337,4 @@ private Object getTownByUuid(final UUID uuid) {
         }
         return town;
     }
-}
+}

teams-api-plugin/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-velocity/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api-velocity/src/main/java/com/skyblockexp/teamsapi/velocity/bridge/VelocityTeamData.java

@@ -141,4 +141,15 @@ public boolean isMember(final UUID playerUUID) {
     public boolean isOwner(final UUID playerUUID) {
         return ownerUUID.equals(playerUUID);
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public Collection<UUID> getMemberUUIDs() {
+        return members.stream()
+            .map(VelocityTeamMember::getPlayerUUID)
+            .collect(java.util.stream.Collectors.toUnmodifiableList());
+    }
+
 }

teams-api-velocity/src/main/java/com/skyblockexp/teamsapi/velocity/model/VelocityTeam.java

@@ -48,7 +48,7 @@ public interface VelocityTeam {
      */
     int getSize();
 
-    /**
+/**
      * Returns the maximum number of members allowed in this team.
      * A value of {@code -1} means the team size is unlimited.
      *
@@ -64,6 +64,16 @@ public interface VelocityTeam {
      */
     Collection<VelocityTeamMember> getMembers();
 
+    /**
+     * Returns the UUIDs of all members in this team, including the owner.
+     *
+     * <p>This is a convenience method equivalent to mapping {@link #getMembers()} by
+     * {@link VelocityTeamMember#getPlayerUUID()}.</p>
+     *
+     * @return an unmodifiable collection of member UUIDs
+     */
+    Collection<UUID> getMemberUUIDs();
+
     /**
      * Looks up a member by their player UUID.
      *
@@ -87,4 +97,16 @@ public interface VelocityTeam {
      * @return true if the player is the owner
      */
     boolean isOwner(UUID playerUUID);
+
+    /**
+     * Returns the {@link VelocityTeamMember} record for the team owner.
+     *
+     * <p>This is a convenience method equivalent to {@code getMember(getOwnerUUID())}.</p>
+     *
+     * @return an {@link Optional} containing the owner's member record
+     */
+    default Optional<VelocityTeamMember> getOwner() {
+        return getMember(getOwnerUUID());
+    }
+
 }

teams-api/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>com.github.ez-plugins</groupId>
         <artifactId>teams-api-parent</artifactId>
-        <version>2.4.0</version>
+        <version>2.5.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

teams-api/src/main/java/com/skyblockexp/teamsapi/api/TeamsAPI.java

@@ -56,7 +56,7 @@ public final class TeamsAPI {
      * compatibility when the API introduces breaking changes. The version follows
      * Semantic Versioning ({@code MAJOR.MINOR.PATCH}).</p>
      */
-    public static final String API_VERSION = "2.4.0";
+    public static final String API_VERSION = "2.5.0";
 
     /**
      * Registry of custom role definitions, keyed by role key.

teams-api/src/main/java/com/skyblockexp/teamsapi/api/TeamsService.java

@@ -96,13 +96,13 @@ public interface TeamsService {
      */
     Optional<Team> getTeamByName(String name);
 
-    /**
-     * Retrieves the team that the given player currently belongs to.
-     *
-     * @param playerUUID the UUID of the player; must not be {@code null}
-     * @return an {@link Optional} containing the player's {@link Team}, or empty if
-     *         the player does not belong to any team
-     */
+/**
+      * Retrieves the team that the given player currently belongs to.
+      *
+      * @param playerUUID the UUID of the player; must not be {@code null}
+      * @return an {@link Optional} containing the player's {@link Team}, or empty if
+      *         the player does not belong to any team
+      */
     Optional<Team> getPlayerTeam(UUID playerUUID);
 
     /**
@@ -119,6 +119,16 @@ public interface TeamsService {
      */
     int getTeamCount();
 
+    /**
+     * Returns the UUIDs of all registered teams.
+     *
+     * <p>This is a convenience method equivalent to mapping {@link #getAllTeams()} by
+     * {@link com.skyblockexp.teamsapi.model.Team#getId()}.</p>
+     *
+     * @return an unmodifiable collection of team UUIDs; never {@code null}
+     */
+    Collection<UUID> getTeamIds();
+
     // -------------------------------------------------------------------------
     // Membership management
     // -------------------------------------------------------------------------

teams-api/src/main/java/com/skyblockexp/teamsapi/model/Team.java

@@ -116,4 +116,17 @@ public interface Team {
      * @return {@code true} if the player holds the {@link TeamRole#OWNER} role
      */
     boolean isOwner(UUID playerUUID);
+
+    /**
+     * Returns the {@link TeamMember} record for the team owner.
+     *
+     * <p>This is a convenience method equivalent to {@code getMember(getOwnerUUID())}.</p>
+     *
+     * @return an {@link Optional} containing the owner's {@link TeamMember}, or empty
+     *         if the team has no owner (should not occur in valid implementations)
+     */
+    default Optional<TeamMember> getOwner() {
+        return getMember(getOwnerUUID());
+    }
+
 }

teams-api/src/main/java/com/skyblockexp/teamsapi/model/TeamRole.java

@@ -116,6 +116,15 @@ public void setPrefixOverride(final String prefix) {
         this.prefixOverride = prefix;
     }
 
+    /**
+     * Clears any prefix override on this role, restoring the built-in default.
+     *
+     * <p>Equivalent to calling {@link #setPrefixOverride(String) setPrefixOverride(null)}.</p>
+     */
+    public void resetPrefixOverride() {
+        this.prefixOverride = null;
+    }
+
     /**
      * Returns {@code true} if this role has a higher priority than {@code other}.
      *