noxaeapi-sdk 0.4.0__py3-none-any.whl

noxaeapi_sdk/modules/worlds.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any, Dict, List
+
+from ..http_engine import HttpEngine
+from ..types import Weather, World
+
+
+def _q(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+class WorldsModule:
+    def __init__(self, http: HttpEngine) -> None:
+        self._http = http
+
+    def list(self) -> List[World]:
+        """List all worlds."""
+        return self._http.request("GET", "worlds")
+
+    def save_all(self) -> None:
+        """Save all worlds to disk."""
+        return self._http.request("POST", "worlds/save")
+
+    def download_all(self) -> Dict[str, str]:
+        """Get a download link/stream reference for all worlds."""
+        return self._http.request("GET", "worlds/download")
+
+    def get(self, uuid: str) -> World:
+        """Get a single world by UUID."""
+        return self._http.request("GET", f"worlds/{_q(uuid)}")
+
+    def save(self, uuid: str) -> None:
+        """Save a specific world to disk."""
+        return self._http.request("POST", f"worlds/{_q(uuid)}/save")
+
+    def download(self, uuid: str) -> Dict[str, str]:
+        """Get a download link/stream reference for a specific world."""
+        return self._http.request("GET", f"worlds/{_q(uuid)}/download")
+
+    def set_time(self, uuid: str, time: int) -> None:
+        """Set the in-game time for a world (0-24000)."""
+        return self._http.request("POST", f"worlds/{_q(uuid)}/time", body={"time": time}, form=True)
+
+    def set_weather(self, uuid: str, weather: Weather) -> None:
+        """Set the weather for a world.
+
+        Server-side (``WorldApi.setWorldWeather``) reads a single
+        ``weather`` enum string — "clear" | "rain" | "thunder" — not
+        separate storm/thundering booleans.
+        """
+        return self._http.request("POST", f"worlds/{_q(uuid)}/weather", body={"weather": weather}, form=True)
+
+    def get_entities(self, uuid: str) -> Dict[str, Any]:
+        """Get entity counts within a specific world."""
+        return self._http.request("GET", f"worlds/{_q(uuid)}/entities")

noxaeapi_sdk/socket.py

@@ -0,0 +1,167 @@
+"""Realtime console/event socket.
+
+Requires the optional ``websocket-client`` dependency:
+
+    pip install noxaeapi-sdk[ws]
+
+The import is lazy — importing :mod:`noxaeapi_sdk` itself never requires
+``websocket-client`` to be installed; only calling
+:meth:`~noxaeapi_sdk.client.NoxAeApiClient.connect` does.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import threading
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set
+
+Listener = Callable[[Any], None]
+
+WS_EVENTS = ("open", "close", "error", "console", "event", "message")
+
+
+def _to_ws_url(base_url: str, route: str, api_key: Optional[str] = None) -> str:
+    parsed = urllib.parse.urlsplit(f"{base_url.rstrip('/')}/v1/ws/{route.lstrip('/')}")
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    query = dict(urllib.parse.parse_qsl(parsed.query))
+    if api_key:
+        query["key"] = api_key
+    new_query = urllib.parse.urlencode(query)
+    return urllib.parse.urlunsplit((scheme, parsed.netloc, parsed.path, new_query, ""))
+
+
+@dataclass
+class NoxAeApiWsOptions:
+    """Options for :class:`NoxAeApiSocket`."""
+
+    base_url: str
+    api_key: Optional[str] = None
+    route: str = "events"
+    """Route suffix under the websocket base, e.g. "console" or "events"."""
+    auto_reconnect: bool = True
+    max_reconnect_delay: float = 30.0
+    """Max reconnect delay in seconds."""
+    extra: Dict[str, Any] = field(default_factory=dict)
+    """Extra kwargs forwarded to ``websocket.WebSocketApp``."""
+
+
+class NoxAeApiSocket:
+    """Thin wrapper around the server's WebSocket endpoints (console tail and event broadcasts).
+
+    Runs the connection on a background thread and handles reconnection
+    with exponential backoff, so consumers can just attach listeners and
+    not think about the socket lifecycle.
+
+    Usage::
+
+        ws = client.connect(route="console")
+        ws.on("console", lambda line: print(line))
+        ws.on("close", lambda _: print("disconnected"))
+    """
+
+    def __init__(self, options: NoxAeApiWsOptions) -> None:
+        try:
+            import websocket  # type: ignore[import-untyped]
+        except ImportError as exc:  # pragma: no cover - exercised only when dep missing
+            raise ImportError(
+                "NoxAeApiSocket requires the optional 'websocket-client' package. "
+                "Install it with: pip install noxaeapi-sdk[ws]"
+            ) from exc
+
+        self._websocket_module = websocket
+        self._options = options
+        self._listeners: Dict[str, Set[Listener]] = {event: set() for event in WS_EVENTS}
+        self._reconnect_attempt = 0
+        self._closed_by_user = False
+        self._app: Optional[Any] = None
+        self._thread: Optional[threading.Thread] = None
+        self._open()
+
+    # -- connection lifecycle -------------------------------------------------
+
+    def _open(self) -> None:
+        url = _to_ws_url(self._options.base_url, self._options.route, self._options.api_key)
+
+        def on_open(_ws: Any) -> None:
+            self._reconnect_attempt = 0
+            self._emit("open", None)
+
+        def on_message(_ws: Any, message: Any) -> None:
+            text = message if isinstance(message, str) else message.decode("utf-8", errors="replace")
+            parsed = _safe_parse(text)
+            self._emit("message", parsed)
+            if isinstance(parsed, dict) and parsed.get("type") in ("console", "event"):
+                self._emit(parsed["type"], parsed)
+
+        def on_error(_ws: Any, error: Any) -> None:
+            self._emit("error", error)
+
+        def on_close(_ws: Any, _status_code: Any, _msg: Any) -> None:
+            self._emit("close", None)
+            if not self._closed_by_user and self._options.auto_reconnect:
+                self._schedule_reconnect()
+
+        self._app = self._websocket_module.WebSocketApp(
+            url,
+            on_open=on_open,
+            on_message=on_message,
+            on_error=on_error,
+            on_close=on_close,
+            **self._options.extra,
+        )
+        self._thread = threading.Thread(target=self._app.run_forever, daemon=True)
+        self._thread.start()
+
+    def _schedule_reconnect(self) -> None:
+        max_delay = self._options.max_reconnect_delay
+        delay = min(max_delay, 0.5 * (2 ** self._reconnect_attempt))
+        self._reconnect_attempt += 1
+
+        def _reconnect() -> None:
+            time.sleep(delay)
+            if not self._closed_by_user:
+                self._open()
+
+        threading.Thread(target=_reconnect, daemon=True).start()
+
+    # -- listeners --------------------------------------------------------
+
+    def on(self, event: str, listener: Listener) -> Callable[[], None]:
+        """Register a listener for ``event``. Returns an unsubscribe callable."""
+        if event not in self._listeners:
+            self._listeners[event] = set()
+        self._listeners[event].add(listener)
+        return lambda: self._listeners.get(event, set()).discard(listener)
+
+    def off(self, event: str, listener: Listener) -> None:
+        self._listeners.get(event, set()).discard(listener)
+
+    def _emit(self, event: str, payload: Any) -> None:
+        for listener in list(self._listeners.get(event, set())):
+            listener(payload)
+
+    # -- send/close ---------------------------------------------------------
+
+    def send(self, payload: Any) -> None:
+        """Send a raw payload over the socket, JSON-encoded if not already a string."""
+        if self._app is None or self._app.sock is None or not self._app.sock.connected:
+            raise RuntimeError("Cannot send: socket is not open")
+        data = payload if isinstance(payload, str) else json.dumps(payload)
+        self._app.send(data)
+
+    def close(self) -> None:
+        """Close the socket and stop reconnecting."""
+        self._closed_by_user = True
+        if self._app is not None:
+            self._app.close()
+
+
+def _safe_parse(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return text

noxaeapi_sdk/types.py

@@ -0,0 +1,305 @@
+"""Response shape hints for the NoxAeApi REST API.
+
+These are :class:`typing.TypedDict` definitions, not runtime-validated
+models — every SDK method still just returns whatever JSON the server
+sent, parsed into plain ``dict``/``list``/scalar values. The TypedDicts
+exist purely so editors and type checkers (mypy/pyright) can give you
+autocomplete and structural checks against the documented shapes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Literal, Optional, Tuple, TypedDict, Union
+
+
+class OnlinePlayer(TypedDict):
+    uuid: str
+    displayName: str
+    address: Optional[str]
+    port: Optional[int]
+    exhaustion: float
+    exp: float
+    expLevel: int
+    whitelisted: bool
+    banned: bool
+    op: bool
+    balance: Optional[float]
+    location: Optional[Tuple[float, float, float]]
+    dimension: Optional[str]
+    health: float
+    hunger: int
+    saturation: float
+    gamemode: str
+    lastPlayed: int
+    authenticated: Optional[bool]
+    registered: Optional[bool]
+
+
+class OfflinePlayer(TypedDict):
+    uuid: str
+    displayName: str
+    whitelisted: bool
+    banned: bool
+    op: bool
+    balance: Optional[float]
+    lastPlayed: int
+
+
+class ServerHealth(TypedDict):
+    cpus: int
+    uptime: int
+    totalMemory: int
+    maxMemory: int
+    freeMemory: int
+
+
+class ServerBan(TypedDict):
+    target: str
+    source: Optional[str]
+    reason: Optional[str]
+    expiration: Optional[str]
+
+
+class WhitelistEntry(TypedDict):
+    uuid: str
+    name: str
+
+
+class ServerInfo(TypedDict):
+    name: str
+    motd: str
+    version: str
+    bukkitVersion: str
+    tps: str
+    health: ServerHealth
+    bannedIps: List[ServerBan]
+    bannedPlayers: List[ServerBan]
+    whitelistedPlayers: List[WhitelistEntry]
+    maxPlayers: int
+    onlinePlayers: int
+
+
+class World(TypedDict):
+    name: str
+    uuid: str
+    time: int
+    storm: bool
+    thundering: bool
+    generateStructures: bool
+    allowAnimals: bool
+    allowMonsters: bool
+    difficulty: str
+    environment: str
+    seed: str
+
+
+class Score(TypedDict):
+    entry: str
+    value: int
+
+
+class Objective(TypedDict):
+    name: str
+    displayName: str
+    criterion: str
+    scores: List[Score]
+    displaySlot: Optional[str]
+
+
+class Scoreboard(TypedDict):
+    objectives: List[str]
+    entries: List[str]
+
+
+class InventoryItem(TypedDict):
+    id: str
+    count: int
+    slot: int
+
+
+class Plugin(TypedDict):
+    name: str
+    enabled: bool
+    version: str
+    website: Optional[str]
+    authors: List[str]
+    depends: List[str]
+    softDepends: List[str]
+    apiVersion: Optional[str]
+    description: Optional[str]
+
+
+class EconomyInfo(TypedDict, total=False):
+    available: bool
+
+
+class PlayerBalance(TypedDict):
+    uuid: str
+    balance: float
+
+
+class TopBalanceEntry(TypedDict):
+    uuid: str
+    balance: float
+
+
+class GroupInfo(TypedDict):
+    name: str
+    permissions: List[str]
+
+
+class PermissionNode(TypedDict):
+    permission: str
+    value: bool
+    expiry: int
+    server: Optional[str]
+    world: Optional[str]
+
+
+class Advancement(TypedDict):
+    key: str
+    criteria: List[str]
+
+
+class NoxAuthPlayerInfo(TypedDict):
+    uuid: str
+    name: str
+    registered: bool
+    authenticated: bool
+    lastIp: Optional[str]
+    lastLoginTime: Optional[int]
+    countryCode: Optional[str]
+    countryName: Optional[str]
+
+
+class PasswordCheckResult(TypedDict):
+    name: str
+    valid: bool
+
+
+class PlayerStats(TypedDict):
+    uuid: str
+    name: str
+    kills: int
+    deaths: int
+    playtime: int
+    blocksPlaced: int
+    blocksBroken: int
+
+
+class SkillInfo(TypedDict):
+    uuid: str
+    skills: dict
+    """Skill name -> level."""
+    powerLevel: int
+
+
+class CurrencyBalance(TypedDict):
+    uuid: str
+    name: Optional[str]
+    currency: str
+    balance: float
+
+
+class CurrencyTopEntry(TypedDict):
+    uuid: str
+    name: str
+    balance: float
+
+
+class LeaderboardSourceInfo(TypedDict):
+    id: str
+    displayName: str
+    available: bool
+    onlineOnly: bool
+    """True if this source can only rank currently-online players (e.g. mcMMO)."""
+
+
+class LeaderboardEntry(TypedDict):
+    uuid: str
+    name: str
+    value: float
+
+
+class NetworkServerStatus(TypedDict):
+    id: str
+    label: str
+    online: bool
+    server: Optional[ServerInfo]
+    players: List[OnlinePlayer]
+
+
+class NetworkPlayersServerEntry(TypedDict):
+    id: str
+    label: str
+    online: bool
+    players: List[OnlinePlayer]
+
+
+class NetworkPlayersResponse(TypedDict):
+    total: int
+    servers: List[NetworkPlayersServerEntry]
+
+
+class NetworkFindPlayerResponse(TypedDict, total=False):
+    found: bool
+    server: str
+    player: OnlinePlayer
+
+
+class NetworkHealthServerEntry(TypedDict, total=False):
+    id: str
+    label: str
+    online: bool
+    tps: Any
+    health: Any
+
+
+class NetworkHealthResponse(TypedDict):
+    servers: List[NetworkHealthServerEntry]
+
+
+NetworkBroadcastResponse = dict
+"""Per-server "success" | "error" result, keyed by network server ID."""
+
+
+class NetworkHubNode(TypedDict):
+    id: str
+    label: str
+    online: bool
+    tps: str
+    onlinePlayers: int
+    maxPlayers: int
+    health: Any
+    """Opaque payload the backend reported in its last heartbeat."""
+    lastHeartbeatAt: int
+    """Unix epoch ms of the last heartbeat received, or 0 if never."""
+
+
+class NetworkHubStatusResponse(TypedDict):
+    network: List[NetworkHubNode]
+
+
+class NetworkHubPlayer(TypedDict, total=False):
+    uuid: str
+    name: str
+    server: str
+    """Backend server ID the player is currently connected to, if known."""
+
+
+class NetworkHubPlayersResponse(TypedDict):
+    total: int
+    players: List[NetworkHubPlayer]
+
+
+class NetworkHubFindPlayerResponse(TypedDict, total=False):
+    found: bool
+    player: NetworkHubPlayer
+
+
+class NetworkHubBroadcastResponse(TypedDict):
+    delivered: int
+
+
+Gamemode = Literal["survival", "creative", "adventure", "spectator"]
+Weather = Literal["clear", "rain", "thunder"]

noxaeapi_sdk-0.4.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: noxaeapi-sdk
+Version: 0.4.0
+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
+Project-URL: Repository, https://github.com/WumXPro/noxaeapi-sdk
+Project-URL: Issues, https://github.com/WumXPro/noxaeapi-sdk/issues
+Author: WumX Labs
+License: MIT
+License-File: LICENSE
+Keywords: bukkit,fabric,minecraft,noxaeapi,noxlydev,paper,rest-client,sdk,spigot,velocity,wumx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: ws
+Requires-Dist: websocket-client>=1.6; extra == 'ws'
+Description-Content-Type: text/markdown
+
+# noxaeapi-sdk
+
+Typed Python SDK for [NoxAeApi](https://github.com/WumXPro/noxaeapi-sdk), a REST + WebSocket API plugin/mod for Minecraft servers — ships for both Fabric and Bukkit/Spigot/PaperMC. The REST surface is identical across platforms, so this SDK works against either without any platform-specific configuration.
+
+Zero required runtime dependencies — uses only the Python standard library (`urllib`) for HTTP. The realtime socket needs one optional extra.
+
+📖 **Docs:** [noxapi.noxlydev.xyz](https://noxapi.noxlydev.xyz)
+
+## Install
+
+```bash
+pip install noxaeapi-sdk
+
+# with realtime console/event socket support:
+pip install "noxaeapi-sdk[ws]"
+```
+
+## Usage
+
+```python
+from noxaeapi_sdk import NoxAeApiClient
+
+client = NoxAeApiClient(base_url="http://localhost:8080", api_key="your-api-key")
+
+players = client.players.list()
+balance = client.economy.get_balance(players[0]["uuid"])
+client.server.broadcast("Hello from the SDK!")
+
+# Multi-currency (ExcellentEconomy), leaderboards, and network aggregator:
+coins = client.economy.get_currency_balance("coins", players[0]["uuid"])
+top = client.leaderboards.get_top("mcmmo-power", limit=10)
+network = client.network.status_all()
+```
+
+### From environment variables
+
+```python
+# Reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from os.environ.
+# If you keep those in a .env file, load it yourself first (e.g. with
+# python-dotenv) — the SDK never reads .env files or os.environ implicitly
+# outside this method.
+client = NoxAeApiClient.from_env()
+```
+
+### Realtime (console tail / events)
+
+Requires the `ws` extra (`pip install "noxaeapi-sdk[ws]"`).
+
+```python
+ws = client.connect(route="console")
+ws.on("console", lambda line: print(line))
+ws.on("close", lambda _: print("disconnected"))
+```
+
+The socket runs on a background thread and auto-reconnects with exponential backoff on unexpected disconnects.
+
+## Error handling
+
+All non-2xx responses raise a subclass of `NoxAeApiError`:
+
+- `NoxAeApiUnauthorizedError` — 401, missing/invalid API key
+- `NoxAeApiForbiddenError` — 403, key valid but not permitted for this endpoint
+- `NoxAeApiNotFoundError` — 404
+- `NoxAeApiRateLimitError` — 429 (SDK auto-retries these by default; raised only once retries are exhausted)
+- `NoxAeApiServerError` — 5xx (also auto-retried by default)
+- `NoxAeApiNetworkError` — request never completed (timeout, DNS, connection refused)
+
+```python
+from noxaeapi_sdk import NoxAeApiForbiddenError
+
+try:
+    client.server.restart()
+except NoxAeApiForbiddenError:
+    print("This API key isn't allowed to restart the server.")
+```
+
+## Request encoding
+
+The server is a Javalin app, and most endpoints read their body with `ctx.formParam(...)` — i.e. `application/x-www-form-urlencoded` — rather than JSON. The SDK follows the same split:
+
+- **Form-urlencoded**: everything in `economy` (including the `economy.get_currency_balance`/`.pay_currency`/etc ExcellentEconomy methods), `players`, `server` (except `luckperms`/`noxauth`), `worlds`, `plugins`, `placeholders`, and `network.broadcast`.
+- **JSON**: `client.luckperms.*` and `client.noxauth.check_password` only — these are read server-side with `ctx.bodyAsClass(...)`.
+- **N/A (GET only)**: `client.leaderboards.*` and most of `client.network.*` are read-only.
+
+If you're extending the SDK, check which encoding the corresponding Javalin handler uses before wiring up a new method, and pass `form=True` to `http.request(...)` if it's form-urlencoded (this is also the more common case). Getting this wrong won't raise a type error — the request just silently sends the wrong content type and the server won't see the field.
+
+## Optional modules
+
+Some modules only work depending on the target server's setup:
+
+- `client.luckperms.*` — requires the LuckPerms mod to be loaded on the server
+- `client.noxauth.*` — requires `noxauth.enabled: true` in the server's `noxaeapi-config.yml`
+- `client.economy.get_currency_balance()`/`.pay_currency()`/`.debit_currency()`/`.set_currency_balance()`/`.get_currency_top()`/`.list_currencies()` — requires ExcellentEconomy (raises a 424 error if it isn't installed)
+- `client.network.*` — requires `network.enabled: true` with at least one backend server configured in the server's config
+
+Calling these against a server without the corresponding feature enabled will fail (typically 404).
+
+## NoxAeApi-Velocity network hub
+
+If your network runs the **NoxAeApi-Velocity** proxy plugin, use `NoxAeApiNetworkHubClient` instead of (or alongside) `NoxAeApiClient` — point it at the hub's own REST port, not a backend server's port. Backend servers push register/heartbeat updates to the hub over WebSocket, so hub calls answer from its in-memory registry rather than fanning out live requests the way `client.network.*` above does — and the response shapes differ accordingly (e.g. `players()` is one flat proxy-wide list, not a per-backend breakdown, and there's no hub equivalent of `network/health` — see each node's `health` field in `status_all()`/`status_by_id()` instead).
+
+```python
+from noxaeapi_sdk import NoxAeApiNetworkHubClient
+
+hub = NoxAeApiNetworkHubClient(base_url="http://localhost:9090", api_key="your-hub-key")  # the hub's api-port, not a backend's port
+
+status = hub.network.status_all()
+players = hub.network.players()
+found = hub.network.find_player(players["players"][0]["uuid"]) if players["players"] else None
+hub.network.broadcast("Hello from the hub!")
+
+# Reach a specific backend's own REST routes through the hub:
+hub.network.forward("survival", "POST", "server/exec", body={"command": "say hi"}, form=True)
+```
+
+Or from environment variables (`NOXAEAPI_HUB_BASE_URL` / `NOXAEAPI_HUB_KEY`, kept separate from `NoxAeApiClient.from_env()`'s `NOXAEAPI_*` vars so a process can hold both clients at once):
+
+```python
+hub = NoxAeApiNetworkHubClient.from_env()
+```
+
+## Configuration
+
+```python
+from noxaeapi_sdk import NoxAeApiClient, RetryOptions
+
+client = NoxAeApiClient(
+    base_url="https://mc.example.com",
+    api_key="...",
+    timeout=10.0,  # per-request timeout in seconds, default 10
+    retry=RetryOptions(
+        attempts=3,        # total attempts including the first, default 3
+        base_delay_ms=300,
+        max_delay_ms=5000,
+    ),
+    # retry=False,         # disable retries entirely
+    headers={"X-Extra": "..."},
+)
+```
+
+## License
+
+MIT