noxaeapi-sdk 0.4.0__tar.gz

noxaeapi_sdk-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WumX Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noxaeapi_sdk-0.4.0/PKG-INFO

@@ -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

noxaeapi_sdk-0.4.0/README.md

@@ -0,0 +1,143 @@
+# 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

noxaeapi_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "noxaeapi-sdk"
+version = "0.4.0"
+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" }
+authors = [{ name = "WumX Labs" }]
+requires-python = ">=3.8"
+keywords = [
+    "minecraft",
+    "fabric",
+    "bukkit",
+    "spigot",
+    "paper",
+    "velocity",
+    "noxaeapi",
+    "noxlydev",
+    "wumx",
+    "rest-client",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+ws = ["websocket-client>=1.6"]
+dev = ["pytest>=7.0", "mypy>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/WumXPro/noxaeapi-sdk"
+Documentation = "https://noxapi.noxlydev.xyz"
+Repository = "https://github.com/WumXPro/noxaeapi-sdk"
+Issues = "https://github.com/WumXPro/noxaeapi-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/noxaeapi_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]

noxaeapi_sdk-0.4.0/src/noxaeapi_sdk/__init__.py

@@ -0,0 +1,41 @@
+"""Typed Python SDK for the NoxAeApi REST + WebSocket API.
+
+(Fabric, Bukkit/Spigot/Paper) and the NoxAeApi-Velocity network hub.
+
+Example::
+
+    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!")
+"""
+
+from .client import NoxAeApiClient, NoxAeApiNetworkHubClient
+from .errors import (
+    NoxAeApiError,
+    NoxAeApiForbiddenError,
+    NoxAeApiNetworkError,
+    NoxAeApiNotFoundError,
+    NoxAeApiRateLimitError,
+    NoxAeApiServerError,
+    NoxAeApiUnauthorizedError,
+)
+from .http_engine import NoxAeApiClientOptions, RetryOptions
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "NoxAeApiClient",
+    "NoxAeApiNetworkHubClient",
+    "NoxAeApiClientOptions",
+    "RetryOptions",
+    "NoxAeApiError",
+    "NoxAeApiUnauthorizedError",
+    "NoxAeApiForbiddenError",
+    "NoxAeApiNotFoundError",
+    "NoxAeApiRateLimitError",
+    "NoxAeApiServerError",
+    "NoxAeApiNetworkError",
+]

noxaeapi_sdk-0.4.0/src/noxaeapi_sdk/client.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from .http_engine import HttpEngine, NoxAeApiClientOptions
+from .modules.economy import EconomyModule
+from .modules.leaderboard import LeaderboardModule
+from .modules.luckperms import LuckPermsModule
+from .modules.misc import AdvancementsModule, PlaceholdersModule
+from .modules.network import NetworkModule
+from .modules.network_hub import NetworkHubModule
+from .modules.noxauth import NoxAuthModule
+from .modules.players import PlayersModule
+from .modules.plugins import PluginsModule
+from .modules.server import ServerModule
+from .modules.skills import SkillsModule
+from .modules.worlds import WorldsModule
+
+
+class NoxAeApiClient:
+    """Client for a NoxAeApi server (Fabric mod or Bukkit/Spigot/Paper plugin).
+
+    Example::
+
+        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!")
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        options: Optional[NoxAeApiClientOptions] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create a client.
+
+        Either pass ``base_url`` (and optionally ``api_key``,
+        ``timeout``, ``retry``, ``headers``, ...) directly, or build a
+        :class:`~noxaeapi_sdk.http_engine.NoxAeApiClientOptions` yourself
+        and pass it as ``options=``.
+        """
+        if options is None:
+            if not base_url:
+                raise ValueError("NoxAeApiClient requires base_url (or options=NoxAeApiClientOptions(...))")
+            options = NoxAeApiClientOptions(base_url=base_url, api_key=api_key, **kwargs)
+
+        self._options = options
+        self._http = HttpEngine(options)
+
+        self.players = PlayersModule(self._http)
+        self.economy = EconomyModule(self._http)
+        self.server = ServerModule(self._http)
+        self.worlds = WorldsModule(self._http)
+        self.plugins = PluginsModule(self._http)
+        self.advancements = AdvancementsModule(self._http)
+        self.placeholders = PlaceholdersModule(self._http)
+        self.luckperms = LuckPermsModule(self._http)
+        """Only works if LuckPerms is loaded on the target server."""
+        self.noxauth = NoxAuthModule(self._http)
+        """Only works if ``noxauth.enabled: true`` is set in the server config."""
+        self.skills = SkillsModule(self._http)
+        """Requires mcMMO and/or AuraSkills to be loaded on the target server."""
+        self.leaderboards = LeaderboardModule(self._http)
+        """Generic ranked leaderboards (economy currencies, mcMMO, AuraSkills, ...)."""
+        self.network = NetworkModule(self._http)
+        """Only works if ``network.enabled: true`` is set in the server config.
+
+        This is NoxAeApi-main's built-in polling aggregator — it lives on
+        the *same* backend server you're already connected to and fans
+        requests out to the other backends listed in that server's own
+        config. If the network is running NoxAeApi-Velocity instead, use
+        :class:`NoxAeApiNetworkHubClient` (pointed at the proxy's hub
+        port) rather than this module — the hub replaces this aggregator
+        with a push model and its response shapes differ.
+        """
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "NoxAeApiClient":
+        """Build a client from environment variables: ``NOXAEAPI_BASE_URL`` and ``NOXAEAPI_KEY``.
+
+        Convenience for scripts. The SDK never reads ``.env`` files or
+        ``os.environ`` implicitly outside of this method — use a library
+        like ``python-dotenv`` in your own app if you want that, then
+        call ``NoxAeApiClient.from_env()`` after it's loaded.
+        """
+        base_url = overrides.pop("base_url", None) or os.environ.get("NOXAEAPI_BASE_URL")
+        api_key = overrides.pop("api_key", None) or os.environ.get("NOXAEAPI_KEY")
+
+        if not base_url:
+            raise ValueError(
+                "NoxAeApiClient.from_env(): NOXAEAPI_BASE_URL is not set and no base_url override was given."
+            )
+
+        return cls(base_url=base_url, api_key=api_key, **overrides)
+
+    def connect(self, route: str = "events", **kwargs: Any) -> Any:
+        """Open a WebSocket connection to the server (console tail or event stream).
+
+        Requires the optional ``websocket-client`` package
+        (``pip install noxaeapi-sdk[ws]``).
+        """
+        from .socket import NoxAeApiSocket, NoxAeApiWsOptions
+
+        return NoxAeApiSocket(
+            NoxAeApiWsOptions(
+                base_url=self._options.base_url,
+                api_key=self._options.api_key,
+                route=route,
+                **kwargs,
+            )
+        )
+
+
+class NoxAeApiNetworkHubClient:
+    """Client for the **NoxAeApi-Velocity** network hub.
+
+    This is a separate plugin that runs on the Velocity proxy, not on any
+    individual backend server. Point ``base_url`` at the hub's own REST
+    port (``NetworkHubConfig``'s ``api-port``), not a backend's port, and
+    use ``NOXAEAPI_HUB_*`` env vars (via :meth:`from_env`) if you keep
+    that separate from a regular backend's ``NOXAEAPI_*`` vars.
+
+    Only exposes ``.network`` — the hub doesn't run any of the other REST
+    modules (players, economy, worlds, ...) that a backend
+    :class:`NoxAeApiClient` does. To reach a specific backend's own
+    routes through the hub, use ``hub.network.forward(id, ...)``.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        options: Optional[NoxAeApiClientOptions] = None,
+        **kwargs: Any,
+    ) -> None:
+        if options is None:
+            if not base_url:
+                raise ValueError(
+                    "NoxAeApiNetworkHubClient requires base_url (or options=NoxAeApiClientOptions(...))"
+                )
+            options = NoxAeApiClientOptions(base_url=base_url, api_key=api_key, **kwargs)
+
+        http = HttpEngine(options)
+        self.network = NetworkHubModule(http)
+        """The network hub's aggregated view of every registered backend node."""
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "NoxAeApiNetworkHubClient":
+        """Build a hub client from environment variables: ``NOXAEAPI_HUB_BASE_URL`` / ``NOXAEAPI_HUB_KEY``.
+
+        Same convenience as ``NoxAeApiClient.from_env()``, under separate
+        env var names so a process can hold both a backend client and a
+        hub client at once without the two colliding.
+        """
+        base_url = overrides.pop("base_url", None) or os.environ.get("NOXAEAPI_HUB_BASE_URL")
+        api_key = overrides.pop("api_key", None) or os.environ.get("NOXAEAPI_HUB_KEY")
+
+        if not base_url:
+            raise ValueError(
+                "NoxAeApiNetworkHubClient.from_env(): NOXAEAPI_HUB_BASE_URL is not set "
+                "and no base_url override was given."
+            )
+
+        return cls(base_url=base_url, api_key=api_key, **overrides)