noxaeapi-sdk 0.4.0__tar.gz → 0.4.1__tar.gz

{noxaeapi_sdk-0.4.0 → noxaeapi_sdk-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: noxaeapi-sdk
-Version: 0.4.0
+Version: 0.4.1
 Summary: Typed Python SDK for the NoxAeApi REST + WebSocket API (Fabric, Bukkit/Spigot/Paper) and the NoxAeApi-Velocity network hub
 Project-URL: Homepage, https://github.com/WumXPro/noxaeapi-sdk
 Project-URL: Documentation, https://noxapi.noxlydev.xyz

{noxaeapi_sdk-0.4.0 → noxaeapi_sdk-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "noxaeapi-sdk"
-version = "0.4.0"
+version = "0.4.1"
 description = "Typed Python SDK for the NoxAeApi REST + WebSocket API (Fabric, Bukkit/Spigot/Paper) and the NoxAeApi-Velocity network hub"
 readme = "README.md"
 license = { text = "MIT" }

noxaeapi_sdk-0.4.1/src/noxaeapi_sdk/modules/leaderboard.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import urllib.parse
+from typing import List, Optional, Sequence
+
+from ..http_engine import HttpEngine
+from ..types import (
+    LeaderboardEntry,
+    LeaderboardSourceInfo,
+    PlayerProfile,
+    PlayerProfilesResponse,
+)
+
+
+def _q(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+class LeaderboardModule:
+    """Wraps the generic, pluggable ``/v1/leaderboards/*`` routes.
+
+    This is a unified view over every ranking source registered on the
+    server — economy currencies, mcMMO power level, AuraSkills power
+    level, etc — so you don't need to know ahead of time which plugins
+    are installed.
+
+    Use :meth:`list` to discover available source IDs, then pass one to
+    :meth:`get_top`. Sources that are registered but currently
+    unavailable (e.g. the backing plugin isn't loaded) raise
+    ``NoxAeApiError`` with the source's own unavailable status (424 for
+    economy currencies, 503 for mcMMO/AuraSkills) when you call
+    :meth:`get_top`.
+
+    This module also wraps the player-profile routes
+    (``/v1/players/{uuid}/profile`` and ``/v1/players/profiles``), which live
+    server-side alongside the leaderboard sources since they're built on top
+    of them.
+    """
+
+    def __init__(self, http: HttpEngine) -> None:
+        self._http = http
+
+    def list(self) -> List[LeaderboardSourceInfo]:
+        """List every registered leaderboard source and its availability."""
+        return self._http.request("GET", "leaderboards")
+
+    def get_top(self, id: str, limit: Optional[int] = None) -> List[LeaderboardEntry]:
+        """Get ranked entries for one leaderboard source (see :meth:`list` for valid IDs)."""
+        return self._http.request("GET", f"leaderboards/{_q(id)}/top", query={"limit": limit})
+
+    def get_player_profile(self, uuid: str) -> PlayerProfile:
+        """One-call player profile: identity, whitelist/ban status, Vault balance,
+        and this player's entry in every registered leaderboard source. Built so
+        clients never have to know how many leaderboard sources exist or scan
+        top-N lists themselves.
+
+        Raises ``NoxAeApiNotFoundError`` if no known player with that UUID has
+        ever joined.
+        """
+        return self._http.request("GET", f"players/{_q(uuid)}/profile")
+
+    def get_player_profiles(
+        self,
+        *,
+        uuids: Optional[Sequence[str]] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+        online_only: Optional[bool] = None,
+    ) -> PlayerProfilesResponse:
+        """Bulk player profiles — same shape as :meth:`get_player_profile`, for many
+        players at once. Computes each leaderboard source's full ranking exactly
+        once for the whole batch rather than once per player, so this is far
+        cheaper than calling :meth:`get_player_profile` in a loop.
+
+        Pass ``uuids`` to fetch an exact, specific set of players — unknown UUIDs
+        are silently skipped rather than raising. Omit ``uuids`` to page through
+        every known player instead, using ``page``/``limit``, optionally narrowed
+        to only currently-online players via ``online_only``.
+        """
+        return self._http.request(
+            "GET",
+            "players/profiles",
+            query={
+                "uuids": ",".join(uuids) if uuids else None,
+                "page": page,
+                "limit": limit,
+                "onlineOnly": online_only,
+            },
+        )

{noxaeapi_sdk-0.4.0 → noxaeapi_sdk-0.4.1}/src/noxaeapi_sdk/modules/players.py

@@ -4,7 +4,14 @@ import urllib.parse
 from typing import Any, Dict, List, Optional, Union
 
 from ..http_engine import HttpEngine
-from ..types import Gamemode, InventoryItem, OfflinePlayer, OnlinePlayer, PlayerStats
+from ..types import (
+    Gamemode,
+    InventoryItem,
+    OfflinePlayer,
+    OnlinePlayer,
+    PlayerResolveResult,
+    PlayerStats,
+)
 
 
 def _q(value: str) -> str:
@@ -27,6 +34,17 @@ class PlayersModule:
         """Get a single player by UUID (works for online or offline players)."""
         return self._http.request("GET", f"players/{_q(uuid)}")
 
+    def resolve(self, name: str) -> PlayerResolveResult:
+        """Resolve a player name to their UUID using the server's own local player cache.
+
+        Works on both online-mode and offline-mode servers, unlike Mojang's public
+        API - the UUID returned matches whatever this server actually uses for that
+        player's stats/economy/etc. Checks currently online players first, then
+        falls back to the server's offline player cache. Raises
+        ``NoxAeApiNotFoundError`` if no known player with that name has ever joined.
+        """
+        return self._http.request("GET", f"players/resolve/{_q(name)}")
+
     def get_inventory(self, player_uuid: str, world_uuid: str) -> List[InventoryItem]:
         """Get a player's inventory in a specific world."""
         return self._http.request("GET", f"players/{_q(player_uuid)}/{_q(world_uuid)}/inventory")

{noxaeapi_sdk-0.4.0 → noxaeapi_sdk-0.4.1}/src/noxaeapi_sdk/types.py

@@ -45,6 +45,13 @@ class OfflinePlayer(TypedDict):
     lastPlayed: int
 
 
+class PlayerResolveResult(TypedDict):
+    """Result of resolving a player name to their UUID via ``GET /players/resolve/{name}``."""
+
+    name: str
+    uuid: str
+
+
 class ServerHealth(TypedDict):
     cpus: int
     uptime: int
@@ -221,6 +228,72 @@ class LeaderboardEntry(TypedDict):
     value: float
 
 
+class PlayerProfileBan(TypedDict, total=False):
+    """Ban details for a player, as reported by ``GET /v1/players/{uuid}/profile``'s ``status.ban``."""
+
+    banned: bool
+    reason: str
+    """Only present when ``banned`` is true."""
+    source: str
+    """Only present when ``banned`` is true."""
+    created: str
+    """Only present when ``banned`` is true. Serialized server-side as a locale-formatted date string, not ISO-8601."""
+    expires: Optional[str]
+    """Only present when ``banned`` is true. ``None``/absent means a permanent ban. Same date-string format as ``created``."""
+
+
+class PlayerProfileStatus(TypedDict):
+    """Whitelist + ban status for a player, as reported by ``GET /v1/players/{uuid}/profile``'s ``status`` field."""
+
+    whitelisted: bool
+    ban: PlayerProfileBan
+
+
+class PlayerProfileEconomy(TypedDict, total=False):
+    """Vault economy info for a player, as reported by ``GET /v1/players/{uuid}/profile``'s ``economy`` field.
+
+    Single-currency (Vault), not ExcellentEconomy's multi-currency system - see
+    :meth:`EconomyModule.get_currency_balance` for that.
+    """
+
+    available: bool
+    balance: float
+    """Only present when ``available`` is true."""
+
+
+class PlayerProfileStatTile(TypedDict, total=False):
+    """One leaderboard source's contribution to a player profile's ``stats`` array."""
+
+    id: str
+    label: str
+    status: Literal["ranked", "not_ranked", "unavailable"]
+    value: float
+    """Only present when ``status`` is "ranked"."""
+    rank: int
+    """Only present when ``status`` is "ranked" and the source reports a positive rank."""
+
+
+class PlayerProfile(TypedDict):
+    """One-call player profile combining identity, whitelist/ban status, Vault balance, and this
+    player's entry in every registered leaderboard source. Returned by
+    ``GET /v1/players/{uuid}/profile`` and (as the ``players`` array) by ``GET /v1/players/profiles``.
+    """
+
+    name: Optional[str]
+    uuid: str
+    online: bool
+    status: PlayerProfileStatus
+    economy: PlayerProfileEconomy
+    stats: List[PlayerProfileStatTile]
+
+
+class PlayerProfilesResponse(TypedDict):
+    """Response shape of ``GET /v1/players/profiles`` (bulk player profiles)."""
+
+    count: int
+    players: List[PlayerProfile]
+
+
 class NetworkServerStatus(TypedDict):
     id: str
     label: str

noxaeapi_sdk-0.4.0/src/noxaeapi_sdk/modules/leaderboard.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-import urllib.parse
-from typing import List, Optional
-
-from ..http_engine import HttpEngine
-from ..types import LeaderboardEntry, LeaderboardSourceInfo
-
-
-def _q(value: str) -> str:
-    return urllib.parse.quote(value, safe="")
-
-
-class LeaderboardModule:
-    """Wraps the generic, pluggable ``/v1/leaderboards/*`` routes.
-
-    This is a unified view over every ranking source registered on the
-    server — economy currencies, mcMMO power level, AuraSkills power
-    level, etc — so you don't need to know ahead of time which plugins
-    are installed.
-
-    Use :meth:`list` to discover available source IDs, then pass one to
-    :meth:`get_top`. Sources that are registered but currently
-    unavailable (e.g. the backing plugin isn't loaded) raise
-    ``NoxAeApiError`` with the source's own unavailable status (424 for
-    economy currencies, 503 for mcMMO/AuraSkills) when you call
-    :meth:`get_top`.
-    """
-
-    def __init__(self, http: HttpEngine) -> None:
-        self._http = http
-
-    def list(self) -> List[LeaderboardSourceInfo]:
-        """List every registered leaderboard source and its availability."""
-        return self._http.request("GET", "leaderboards")
-
-    def get_top(self, id: str, limit: Optional[int] = None) -> List[LeaderboardEntry]:
-        """Get ranked entries for one leaderboard source (see :meth:`list` for valid IDs)."""
-        return self._http.request("GET", f"leaderboards/{_q(id)}/top", query={"limit": limit})