Features & Architecture

Zero Runtime Dependencies

Ultra lightweight, leveraging native fetch and native WebSocket APIs.

Cross-Platform Identical

Identical REST surface across Fabric, Bukkit, Spigot, and PaperMC.

Auto-Reconnect & Backoff

Automatic exponential backoff reconnects on unexpected socket drops.

Typed Error Hierarchy

Comprehensive error subclasses for 401, 403, 404, 429, 5xx, and network timeouts.

Installation

Install the package from npm via your package manager of choice:

Terminal

npm install @wumx-labs/noxaeapi-sdk
# pnpm
pnpm add @wumx-labs/noxaeapi-sdk
# yarn
yarn add @wumx-labs/noxaeapi-sdk
# bun
bun add @wumx-labs/noxaeapi-sdk

Basic Usage

Initialize the client with your server baseUrl and secret API key:

index.ts

import { NoxAeApiClient } from "@wumx-labs/noxaeapi-sdk";

const client = new NoxAeApiClient({
  baseUrl: "http://localhost:8080",
  apiKey: "your-api-key",
});

// 1. Players & Server moderation
const players = await client.players.list();
await client.server.broadcast("Hello from the TypeScript SDK!");

// 2. Deterministic cross-server identity (v0.5.2)
const identity = await client.identity.get("NoxlyDev");
console.log(identity.identityUuid, identity.hasPlayedBefore);

// 3. Economy & Pluggable Leaderboards
const balance = await client.economy.getBalance(players[0]?.uuid);
const topScores = await client.leaderboards.getTop("mcmmo-power", 10);
const profile = await client.leaderboards.getPlayerProfile(players[0]?.uuid);

From Environment Variables

You can automatically read credentials from the environment with NoxAeApiClient.fromEnv():

env-setup.ts

import { NoxAeApiClient } from "@wumx-labs/noxaeapi-sdk";

// Reads NOXAEAPI_BASE_URL (or NOXAEAPI_URL) and NOXAEAPI_KEY from process.env.
// In Node.js environments using a .env file, load it first (e.g. with dotenv):
// import "dotenv/config";

// 1. Standard environment variable loading
const client = NoxAeApiClient.fromEnv();

// 2. Or pass a custom environment dictionary and client options
const customClient = NoxAeApiClient.fromEnv(process.env, {
  timeoutMs: 15_000,
});

Environment Note

Reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from process.env. If you use a .env file, load it first (e.g. with dotenv) — the SDK never reads .env files implicitly.

Realtime (Console Tail / Events)

Stream server console logs and live events directly using WebSockets:

realtime.ts

import { NoxAeApiClient } from "@wumx-labs/noxaeapi-sdk";

const client = NoxAeApiClient.fromEnv();

// 1. Connect to live console output stream (authenticates via ?key= query parameter)
const consoleSocket = client.connect({ route: "console" });

consoleSocket.on("open", () => console.log("Connected to console stream"));
consoleSocket.on("console", (line) => console.log("[Minecraft Console]", line));
consoleSocket.on("error", (err) => console.error("WebSocket error:", err));
consoleSocket.on("close", () => console.log("Console connection closed"));

// 2. Connect to live game events (joins, quits, deaths, kicks, bans, chat)
const eventsSocket = client.connect({ route: "events" });

eventsSocket.on("event", (evt) => {
  console.log("Live Event:", evt.event, "Player:", evt.player?.name);
});

// Sockets include built-in automatic reconnect with exponential backoff.

Error Handling

All non-2xx responses throw a typed subclass of NoxAeApiError:

Error Classes

NoxAeApiUnauthorizedError401 — Missing or invalid API key

NoxAeApiForbiddenError403 — Key valid but not permitted for this endpoint

NoxAeApiNotFoundError404 — Resource or player not found

NoxAeApiRateLimitError429 — Rate limited (SDK auto-retries these by default)

NoxAeApiServerError5xx — Server error (also auto-retried by default)

NoxAeApiNetworkErrorRequest never completed (timeout, DNS, connection refused)

errors.ts

import {
  NoxAeApiForbiddenError,
  NoxAeApiNotFoundError,
  NoxAeApiRateLimitError,
} from "@wumx-labs/noxaeapi-sdk";

try {
  await client.server.restart();
} catch (err) {
  if (err instanceof NoxAeApiForbiddenError) {
    console.error("This API key isn't allowed to restart the server.");
  } else if (err instanceof NoxAeApiNotFoundError) {
    console.error("The requested resource was not found.");
  } else if (err instanceof NoxAeApiRateLimitError) {
    console.error("Rate limit hit, consider lowering request frequency.");
  } else {
    throw err;
  }
}

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, players, server (except luckperms/noxauth), worlds, plugins, and placeholders.
JSON: client.luckperms.* & client.noxauth.checkPassword only — these are read server-side with ctx.bodyAsClass(...).

SDK Modules & Methods

The NoxAeApiClient exposes 10 modular services covering all core Minecraft server subsystems and integrated third-party plugins:

client.players.list(): Promise<OnlinePlayer[]>

1. Player Moderation & Teleportation

2. World Control & Backup Archiving

3. Runtime Plugin Management

4. LuckPerms Permissions & mcMMO Skills