NoxAeApi

@wumx-labs/noxaeapi-sdk

Official JS / TS SDK

Typed JS/TS SDK for NoxAeApi, a REST + WebSocket API plugin/mod for Minecraft servers — ships for both Fabric and Bukkit/Spigot/PaperMC.

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",
});

const players = await client.players.list();
const balance = await client.economy.getBalance(players[0].uuid);
await client.server.broadcast("Hello from the SDK!");

From Environment Variables

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

env-setup.ts
// Reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from process.env.
// If you keep those in a .env file, load it yourself first (e.g. with `dotenv`) —
// the SDK never reads .env files or process.env implicitly outside this method.
const client = NoxAeApiClient.fromEnv();

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
const ws = client.connect({ route: "console" });

ws.on("console", (line) => console.log(line));
ws.on("close", () => console.log("disconnected"));

// The socket auto-reconnects with exponential backoff on unexpected disconnects.

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 } 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 {
    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(...).

Optional Modules

Some modules only work depending on the target server setup:

client.luckperms.*

Requires the LuckPerms plugin/mod to be loaded on the Minecraft server.

client.noxauth.*

Requires noxauth.enabled: true in the server’s config.yml.

Advanced Configuration

Fine-tune timeout limits, retry strategies, and custom headers in the constructor:

client-options.ts
new NoxAeApiClient({
  baseUrl: "https://mc.example.com",
  apiKey: "...",
  timeoutMs: 10_000,          // per-request timeout, default 10s
  retry: {
    attempts: 3,               // total attempts including the first, default 3
    baseDelayMs: 300,
    maxDelayMs: 5000,
  },
  // retry: false,             // disable retries entirely
  headers: { "X-Extra": "..." },
});
Explore Full API ReferenceMore Code Examples