noxaeapi-sdk 0.4.0__py3-none-any.whl

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/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)

noxaeapi_sdk/errors.py

@@ -0,0 +1,132 @@
+"""Exception hierarchy for the NoxAeApi SDK.
+
+Every non-2xx HTTP response from a NoxAeApi server raises a subclass of
+:class:`NoxAeApiError`. Network-level failures (DNS, connection refused,
+timeouts) raise :class:`NoxAeApiNetworkError` instead, which is *not* a
+subclass of :class:`NoxAeApiError` since no response was ever received.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class NoxAeApiError(Exception):
+    """Base error for any non-2xx response from a NoxAeApi server.
+
+    Prefer catching one of the more specific subclasses below when you
+    need to branch on the failure reason.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        method: str,
+        path: str,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.method = method
+        self.path = path
+        self.body = body
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{type(self).__name__}(status={self.status}, method={self.method!r}, path={self.path!r})"
+
+
+class NoxAeApiUnauthorizedError(NoxAeApiError):
+    """401 — the API key is missing or not recognized by the server."""
+
+    def __init__(self, *, status: int, method: str, path: str, body: Any = None) -> None:
+        super().__init__(
+            f"Unauthorized: the API key was missing or invalid for {method} {path}",
+            status=status,
+            method=method,
+            path=path,
+            body=body,
+        )
+
+
+class NoxAeApiForbiddenError(NoxAeApiError):
+    """403 — the key is valid but isn't allowed to call this endpoint.
+
+    This is a server-side permission decision (e.g. a read-only key
+    hitting a write route); the SDK does not try to predict or enforce
+    it client-side.
+    """
+
+    def __init__(self, *, status: int, method: str, path: str, body: Any = None) -> None:
+        super().__init__(
+            f"Forbidden: this API key does not have permission to call {method} {path}",
+            status=status,
+            method=method,
+            path=path,
+            body=body,
+        )
+
+
+class NoxAeApiNotFoundError(NoxAeApiError):
+    """404 — the target resource (player, world, plugin, etc.) wasn't found."""
+
+    def __init__(self, *, status: int, method: str, path: str, body: Any = None) -> None:
+        super().__init__(
+            f"Not found: {method} {path}",
+            status=status,
+            method=method,
+            path=path,
+            body=body,
+        )
+
+
+class NoxAeApiRateLimitError(NoxAeApiError):
+    """429 — rate limited.
+
+    ``retry_after_ms`` is populated when the server sends a
+    ``Retry-After`` header. The SDK auto-retries these by default; this
+    is only raised once retries are exhausted (or retries are disabled).
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        method: str,
+        path: str,
+        body: Any = None,
+        retry_after_ms: Optional[int] = None,
+    ) -> None:
+        suffix = f" — retry after {retry_after_ms}ms" if retry_after_ms else ""
+        super().__init__(
+            f"Rate limited on {method} {path}{suffix}",
+            status=status,
+            method=method,
+            path=path,
+            body=body,
+        )
+        self.retry_after_ms = retry_after_ms
+
+
+class NoxAeApiServerError(NoxAeApiError):
+    """5xx — the server errored out. Usually safe to retry, and auto-retried by default."""
+
+    def __init__(self, *, status: int, method: str, path: str, body: Any = None) -> None:
+        super().__init__(
+            f"Server error ({status}) on {method} {path}",
+            status=status,
+            method=method,
+            path=path,
+            body=body,
+        )
+
+
+class NoxAeApiNetworkError(Exception):
+    """The request could not complete at all (DNS, connection refused, timeout)."""
+
+    def __init__(self, message: str, *, method: str, path: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.method = method
+        self.path = path
+        self.__cause__ = cause

noxaeapi_sdk/http_engine.py

@@ -0,0 +1,259 @@
+"""Low-level HTTP engine shared by every module.
+
+Zero third-party runtime dependencies — built on ``urllib`` from the
+standard library, mirroring the zero-dependency ethos of the original
+JS/TS SDK (which uses native ``fetch``).
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional, Union
+
+from .errors import (
+    NoxAeApiError,
+    NoxAeApiForbiddenError,
+    NoxAeApiNetworkError,
+    NoxAeApiNotFoundError,
+    NoxAeApiRateLimitError,
+    NoxAeApiServerError,
+    NoxAeApiUnauthorizedError,
+)
+
+Method = str  # "GET" | "POST" | "PUT" | "DELETE" | "PATCH"
+QueryValue = Union[str, int, float, bool, None]
+
+
+@dataclass
+class RetryOptions:
+    """Retry behavior for network errors, 429s, and 5xx responses."""
+
+    attempts: int = 3
+    """Max number of attempts including the first one. Default 3."""
+
+    base_delay_ms: int = 300
+    """Base delay in ms used for exponential backoff."""
+
+    max_delay_ms: int = 5000
+    """Upper bound for any single backoff delay."""
+
+
+@dataclass
+class NoxAeApiClientOptions:
+    """Options accepted by :class:`NoxAeApiClient` / :class:`NoxAeApiNetworkHubClient`."""
+
+    base_url: str
+    """Base URL of the server, e.g. ``"http://localhost:8080"``."""
+
+    api_key: Optional[str] = None
+    """The API key configured on the server (sent as the ``key`` header)."""
+
+    timeout: float = 10.0
+    """Request timeout in seconds. Default 10."""
+
+    retry: Union[RetryOptions, bool, None] = True
+    """Retry options, ``True`` for defaults, or ``False`` to disable retries."""
+
+    headers: Dict[str, str] = field(default_factory=dict)
+    """Extra headers sent on every request."""
+
+    opener: Optional[Callable[[urllib.request.Request, float], Any]] = None
+    """Override the low-level opener, mainly for testing.
+
+    Must be a callable ``(request, timeout) -> http.client.HTTPResponse``
+    (or a context-manager-compatible object with the same interface as
+    what ``urllib.request.urlopen`` returns). Defaults to
+    ``urllib.request.urlopen``.
+    """
+
+
+def _resolve_retry(retry: Union[RetryOptions, bool, None]) -> Union[RetryOptions, None]:
+    if retry is False or retry is None:
+        return None
+    if retry is True:
+        return RetryOptions()
+    return retry
+
+
+def _sleep(seconds: float) -> None:
+    if seconds > 0:
+        time.sleep(seconds)
+
+
+def _backoff_delay_seconds(attempt: int, opts: RetryOptions) -> float:
+    exp = min(opts.max_delay_ms, opts.base_delay_ms * (2 ** attempt))
+    # full jitter
+    return (random.random() * exp) / 1000.0
+
+
+def _encode_form_body(body: Any) -> bytes:
+    """Encode a plain dict as ``application/x-www-form-urlencoded``.
+
+    Matches what Javalin's ``ctx.formParam(name)`` reads server-side.
+    ``None`` values are omitted so optional fields can be left out
+    entirely rather than sent as the literal string "None".
+    """
+    params: list[tuple[str, str]] = []
+    if isinstance(body, dict):
+        for key, value in body.items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                params.append((key, "true" if value else "false"))
+            elif isinstance(value, (str, int, float)):
+                params.append((key, str(value)))
+            else:
+                params.append((key, json.dumps(value)))
+    return urllib.parse.urlencode(params).encode("utf-8")
+
+
+def _safe_json_parse(text: Optional[str]) -> Any:
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return text
+
+
+def _parse_retry_after(header_value: str) -> Optional[int]:
+    try:
+        return int(float(header_value) * 1000)
+    except ValueError:
+        pass
+    try:
+        from email.utils import parsedate_to_datetime
+
+        dt = parsedate_to_datetime(header_value)
+        if dt is None:
+            return None
+        delta_ms = (dt.timestamp() - time.time()) * 1000
+        return max(0, int(delta_ms))
+    except (TypeError, ValueError):
+        return None
+
+
+class HttpEngine:
+    """Handles request building, encoding, retries, and error mapping."""
+
+    def __init__(self, options: NoxAeApiClientOptions) -> None:
+        if not options.base_url:
+            raise ValueError("NoxAeApiClient requires a non-empty base_url")
+        self._base_url = options.base_url.rstrip("/")
+        self._api_key = options.api_key
+        self._timeout = options.timeout
+        self._retry = _resolve_retry(options.retry)
+        self._extra_headers = dict(options.headers or {})
+        self._opener = options.opener or (
+            lambda req, timeout: urllib.request.urlopen(req, timeout=timeout)
+        )
+
+    def _build_url(self, path: str, query: Optional[Dict[str, QueryValue]] = None) -> str:
+        url = f"{self._base_url}/v1/{path.lstrip('/')}"
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url += "?" + urllib.parse.urlencode(filtered)
+        return url
+
+    def request(
+        self,
+        method: Method,
+        path: str,
+        *,
+        body: Any = None,
+        query: Optional[Dict[str, QueryValue]] = None,
+        form: bool = False,
+    ) -> Any:
+        """Perform a request and return the parsed JSON body (or ``None`` for empty/204 responses)."""
+        url = self._build_url(path, query)
+        max_attempts = self._retry.attempts if self._retry else 1
+
+        last_error: Optional[BaseException] = None
+
+        for attempt in range(max_attempts):
+            headers: Dict[str, str] = {"Accept": "application/json", **self._extra_headers}
+            if self._api_key:
+                headers["key"] = self._api_key
+
+            data: Optional[bytes] = None
+            if body is not None:
+                if form:
+                    headers["Content-Type"] = "application/x-www-form-urlencoded"
+                    data = _encode_form_body(body)
+                else:
+                    headers["Content-Type"] = "application/json"
+                    data = json.dumps(body).encode("utf-8")
+
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+            try:
+                with self._opener(req, self._timeout) as response:
+                    status = response.status
+                    raw = response.read()
+                    text = raw.decode("utf-8") if raw else ""
+                    if status == 204 or not text:
+                        return None
+                    return json.loads(text)
+
+            except urllib.error.HTTPError as http_err:
+                error_text = http_err.read().decode("utf-8", errors="replace") if http_err.fp else None
+                parsed_body = _safe_json_parse(error_text)
+                status = http_err.code
+                info = dict(status=status, method=method, path=path, body=parsed_body)
+
+                if status == 401:
+                    raise NoxAeApiUnauthorizedError(**info) from None
+                if status == 403:
+                    raise NoxAeApiForbiddenError(**info) from None
+                if status == 404:
+                    raise NoxAeApiNotFoundError(**info) from None
+
+                if status == 429:
+                    retry_after_header = http_err.headers.get("Retry-After") if http_err.headers else None
+                    retry_after_ms = _parse_retry_after(retry_after_header) if retry_after_header else None
+                    err = NoxAeApiRateLimitError(retry_after_ms=retry_after_ms, **info)
+                    if self._retry and attempt < max_attempts - 1:
+                        last_error = err
+                        _sleep((retry_after_ms / 1000.0) if retry_after_ms else _backoff_delay_seconds(attempt, self._retry))
+                        continue
+                    raise err from None
+
+                if status >= 500:
+                    err = NoxAeApiServerError(**info)
+                    if self._retry and attempt < max_attempts - 1:
+                        last_error = err
+                        _sleep(_backoff_delay_seconds(attempt, self._retry))
+                        continue
+                    raise err from None
+
+                raise NoxAeApiError(f"Unexpected status {status} on {method} {path}", **info) from None
+
+            except NoxAeApiError:
+                raise
+
+            except Exception as err:  # noqa: BLE001 - network/timeout/DNS errors of many types
+                is_timeout = isinstance(err, TimeoutError) or "timed out" in str(err).lower()
+                message = (
+                    f"Request timed out after {self._timeout}s: {method} {path}"
+                    if is_timeout
+                    else f"Network error on {method} {path}: {err}"
+                )
+                network_err = NoxAeApiNetworkError(message, method=method, path=path, cause=err)
+
+                if self._retry and attempt < max_attempts - 1:
+                    last_error = network_err
+                    _sleep(_backoff_delay_seconds(attempt, self._retry))
+                    continue
+                raise network_err from err
+
+        # Unreachable in practice.
+        if isinstance(last_error, BaseException):
+            raise last_error
+        raise RuntimeError("Request failed after retries")

noxaeapi_sdk/modules/economy.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import urllib.parse
+from typing import List, Literal, Optional
+
+from ..http_engine import HttpEngine
+from ..types import CurrencyBalance, CurrencyTopEntry, EconomyInfo, PlayerBalance, TopBalanceEntry
+
+
+def _q(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+class EconomyModule:
+    def __init__(self, http: HttpEngine) -> None:
+        self._http = http
+
+    def info(self) -> EconomyInfo:
+        """Get info about the connected economy provider (Impactor on Fabric, Vault on Bukkit/Spigot/Paper)."""
+        return self._http.request("GET", "economy")
+
+    def get_balance(self, uuid: str) -> PlayerBalance:
+        """Get a player's balance."""
+        return self._http.request("GET", f"economy/balance/{_q(uuid)}")
+
+    def get_top_balance(self, limit: Optional[int] = None) -> List[TopBalanceEntry]:
+        """Get the top balances leaderboard."""
+        return self._http.request("GET", "economy/top", query={"limit": limit})
+
+    def pay(self, uuid: str, amount: float) -> None:
+        """Pay an amount to a player (adds to their balance)."""
+        return self._http.request("POST", "economy/pay", body={"uuid": uuid, "amount": amount}, form=True)
+
+    def debit(self, uuid: str, amount: float) -> None:
+        """Debit an amount from a player (subtracts from their balance)."""
+        return self._http.request("POST", "economy/debit", body={"uuid": uuid, "amount": amount}, form=True)
+
+    # --- ExcellentEconomy multi-currency (native API, not Vault) ----------
+    #
+    # These endpoints talk directly to ExcellentEconomy's Developer API
+    # rather than Vault, so they work with any currency configured on the
+    # server (coins, gems, tokens, ...) instead of only the single
+    # Vault-linked "primary" currency exposed above. They raise
+    # `NoxAeApiError` with a 424 status if ExcellentEconomy isn't installed
+    # on the target server, and a 404 if the given currency ID doesn't exist.
+
+    def list_currencies(self) -> List[str]:
+        """List all currency IDs configured on ExcellentEconomy."""
+        return self._http.request("GET", "economy/currencies")
+
+    def get_currency_balance(self, currency: str, uuid: str) -> CurrencyBalance:
+        """Get a player's balance for a specific ExcellentEconomy currency."""
+        return self._http.request("GET", f"economy/currency/{_q(currency)}/balance/{_q(uuid)}")
+
+    def pay_currency(self, currency: str, uuid: str, amount: float) -> Literal["success", "failure"]:
+        """Pay a player in a specific currency (adds ``amount``). ``amount`` must be > 0."""
+        return self._http.request(
+            "POST", f"economy/currency/{_q(currency)}/pay", body={"uuid": uuid, "amount": amount}, form=True
+        )
+
+    def debit_currency(self, currency: str, uuid: str, amount: float) -> Literal["success", "failure"]:
+        """Debit a player in a specific currency (subtracts ``amount``). ``amount`` must be > 0."""
+        return self._http.request(
+            "POST", f"economy/currency/{_q(currency)}/debit", body={"uuid": uuid, "amount": amount}, form=True
+        )
+
+    def set_currency_balance(self, currency: str, uuid: str, amount: float) -> Literal["success", "failure"]:
+        """Set a player's balance for a specific currency to an exact amount (``amount`` must be >= 0)."""
+        return self._http.request(
+            "POST", f"economy/currency/{_q(currency)}/set", body={"uuid": uuid, "amount": amount}, form=True
+        )
+
+    def get_currency_top(self, currency: str, limit: Optional[int] = None) -> List[CurrencyTopEntry]:
+        """Get the top balances leaderboard for a specific currency."""
+        return self._http.request("GET", f"economy/currency/{_q(currency)}/top", query={"limit": limit})