@wumx-labs/noxaeapi-sdk 0.1.0 → 0.2.0

package/README.md

@@ -69,6 +69,23 @@ try {
 }
 ```
 
+## 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.*` and `client.noxauth.checkPassword` only —
+  these are read server-side with `ctx.bodyAsClass(...)`.
+
+If you're adding a new SDK method, check which one the corresponding
+Javalin handler uses before wiring it up, and pass `form: true` to
+`http.request(...)` if it's form-urlencoded (this is also the more common
+case). Getting this wrong won't throw 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:
@@ -97,4 +114,4 @@ new NoxAeApiClient({
 
 ## License
 
-MIT
+MIT

package/dist/index.cjs

@@ -107,7 +107,7 @@ var HttpEngine = class {
     this.fetchImpl = fetchImpl;
   }
   buildUrl(path, query) {
-    const url = new URL(`${this.baseUrl}/${path.replace(/^\/+/, "")}`);
+    const url = new URL(`${this.baseUrl}/v1/${path.replace(/^\/+/, "")}`);
     if (query) {
       for (const [key, value] of Object.entries(query)) {
         if (value !== void 0 && value !== null) {
@@ -130,11 +130,20 @@ var HttpEngine = class {
           ...this.extraHeaders
         };
         if (this.apiKey) headers["key"] = this.apiKey;
-        if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+        let encodedBody;
+        if (opts.body !== void 0) {
+          if (opts.form) {
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+            encodedBody = encodeFormBody(opts.body);
+          } else {
+            headers["Content-Type"] = "application/json";
+            encodedBody = JSON.stringify(opts.body);
+          }
+        }
         const response = await this.fetchImpl(url, {
           method,
           headers,
-          body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+          body: encodedBody,
           signal: controller.signal
         });
         clearTimeout(timeout);
@@ -194,6 +203,19 @@ var HttpEngine = class {
     throw lastError instanceof Error ? lastError : new Error("Request failed after retries");
   }
 };
+function encodeFormBody(body) {
+  const params = new URLSearchParams();
+  if (body && typeof body === "object") {
+    for (const [key, value] of Object.entries(body)) {
+      if (value === void 0 || value === null) continue;
+      params.set(
+        key,
+        typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value)
+      );
+    }
+  }
+  return params.toString();
+}
 function safeJsonParse(text) {
   if (!text) return void 0;
   try {
@@ -238,13 +260,18 @@ var PlayersModule = class {
   /** Kick an online player, optionally with a reason. */
   kick(uuid, reason) {
     return this.http.request("POST", `players/${encodeURIComponent(uuid)}/kick`, {
-      body: reason ? { reason } : void 0
+      body: reason ? { reason } : void 0,
+      form: true
     });
   }
-  /** Ban a player, optionally with a reason and expiration. */
-  ban(uuid, reason) {
+  /**
+   * Ban a player, optionally with a reason and an ISO-8601 expiry
+   * (e.g. "2030-01-01T00:00:00Z"). Omit `expiry` for a permanent ban.
+   */
+  ban(uuid, reason, expiry) {
     return this.http.request("POST", `players/${encodeURIComponent(uuid)}/ban`, {
-      body: reason ? { reason } : void 0
+      body: reason || expiry ? { reason, expiry } : void 0,
+      form: true
     });
   }
   /** Remove a player's ban. */
@@ -254,13 +281,15 @@ var PlayersModule = class {
   /** Teleport a player to a location. */
   teleport(uuid, location) {
     return this.http.request("POST", `players/${encodeURIComponent(uuid)}/teleport`, {
-      body: location
+      body: location,
+      form: true
     });
   }
   /** Change a player's gamemode. */
   setGamemode(uuid, gamemode) {
     return this.http.request("PUT", `players/${encodeURIComponent(uuid)}/gamemode`, {
-      body: { gamemode }
+      body: { gamemode },
+      form: true
     });
   }
   /** Get kill/death/playtime/block stats for a player. */
@@ -291,11 +320,11 @@ var EconomyModule = class {
   }
   /** Pay an amount to a player (adds to their balance). */
   pay(uuid, amount) {
-    return this.http.request("POST", "economy/pay", { body: { uuid, amount } });
+    return this.http.request("POST", "economy/pay", { body: { uuid, amount }, form: true });
   }
   /** Debit an amount from a player (subtracts from their balance). */
   debit(uuid, amount) {
-    return this.http.request("POST", "economy/debit", { body: { uuid, amount } });
+    return this.http.request("POST", "economy/debit", { body: { uuid, amount }, form: true });
   }
 };
 
@@ -314,23 +343,40 @@ var ServerModule = class {
     return this.http.request("GET", "server");
   }
   /**
-   * Run a console command on the server.
+   * Run a console command on the server, returning its console output.
    * This is a privileged endpoint — requires a write-enabled API key.
+   *
+   * `waitMs` is how long to wait for output before returning (server
+   * default 500ms if omitted). The server returns the joined output as a
+   * plain JSON string, not `{ lines }`.
    */
-  exec(command) {
-    return this.http.request("POST", "server/exec", { body: { command } });
+  exec(command, waitMs) {
+    return this.http.request("POST", "server/exec", {
+      body: { command, time: waitMs },
+      form: true
+    });
   }
   /** List server operators. */
   getOps() {
     return this.http.request("GET", "server/ops");
   }
-  /** Grant operator status to a player. */
+  /**
+   * Grant operator status to a player.
+   *
+   * Server-side (`ServerApi.opPlayer`) reads `ctx.formParam("playerUuid")`,
+   * not "uuid" — the field name matters here.
+   */
   opPlayer(uuid) {
-    return this.http.request("POST", "server/ops", { body: { uuid } });
+    return this.http.request("POST", "server/ops", { body: { playerUuid: uuid }, form: true });
   }
-  /** Revoke operator status from a player. */
+  /**
+   * Revoke operator status from a player.
+   *
+   * Server-side (`ServerApi.deopPlayer`) reads this from the query string
+   * (`ctx.queryParam("playerUuid")`), not the request body.
+   */
   deopPlayer(uuid) {
-    return this.http.request("DELETE", "server/ops", { body: { uuid } });
+    return this.http.request("DELETE", "server/ops", { query: { playerUuid: uuid } });
   }
   /** Get the current whitelist. */
   getWhitelist() {
@@ -338,11 +384,16 @@ var ServerModule = class {
   }
   /** Add a player to the whitelist. */
   addToWhitelist(uuid, name) {
-    return this.http.request("POST", "server/whitelist", { body: { uuid, name } });
+    return this.http.request("POST", "server/whitelist", { body: { uuid, name }, form: true });
   }
-  /** Remove a player from the whitelist. */
+  /**
+   * Remove a player from the whitelist.
+   *
+   * Server-side (`ServerApi.whitelistDelete`) reads `uuid`/`name` from the
+   * query string, not the request body.
+   */
   removeFromWhitelist(uuid) {
-    return this.http.request("DELETE", "server/whitelist", { body: { uuid } });
+    return this.http.request("DELETE", "server/whitelist", { query: { uuid } });
   }
   /**
    * Restart the server.
@@ -365,7 +416,7 @@ var ServerModule = class {
   }
   /** Ban an IP address. */
   banIp(ip, reason) {
-    return this.http.request("POST", "server/ban-ip", { body: { ip, reason } });
+    return this.http.request("POST", "server/ban-ip", { body: { ip, reason }, form: true });
   }
   /** Get a scoreboard objective's scores by objective name. */
   getObjective(name) {
@@ -378,22 +429,33 @@ var ServerModule = class {
   /** Set a score for an entry on an objective. */
   setScore(objective, entry, value) {
     return this.http.request("POST", `scoreboard/${encodeURIComponent(objective)}/score`, {
-      body: { entry, value }
+      body: { entry, value },
+      form: true
     });
   }
-  /** Reset (remove) a score for an entry on an objective. */
+  /**
+   * Reset (remove) a score for an entry on an objective.
+   *
+   * Server-side (`ServerApi.resetScore`) reads `entry` from the query
+   * string, not the request body.
+   */
   resetScore(objective, entry) {
     return this.http.request("DELETE", `scoreboard/${encodeURIComponent(objective)}/score`, {
-      body: { entry }
+      query: { entry }
     });
   }
   /** Broadcast a message to every player on the server. */
   broadcast(message) {
-    return this.http.request("POST", "chat/broadcast", { body: { message } });
+    return this.http.request("POST", "chat/broadcast", { body: { message }, form: true });
   }
-  /** Send a private message to a specific player. */
+  /**
+   * Send a private message to a specific player.
+   *
+   * Server-side (`ServerApi.tellPost`) reads `ctx.formParam("playerUuid")`,
+   * not "uuid".
+   */
   tell(uuid, message) {
-    return this.http.request("POST", "chat/tell", { body: { uuid, message } });
+    return this.http.request("POST", "chat/tell", { body: { playerUuid: uuid, message }, form: true });
   }
 };
 
@@ -427,16 +489,24 @@ var WorldsModule = class {
   download(uuid) {
     return this.http.request("GET", `worlds/${encodeURIComponent(uuid)}/download`);
   }
-  /** Set the in-game time for a world. */
+  /** Set the in-game time for a world (0-24000). */
   setTime(uuid, time) {
     return this.http.request("POST", `worlds/${encodeURIComponent(uuid)}/time`, {
-      body: { time }
+      body: { time },
+      form: true
     });
   }
-  /** Set weather (storm/thundering) for a world. */
+  /**
+   * Set the weather for a world.
+   *
+   * Server-side (`WorldApi.setWorldWeather`) reads a single
+   * `ctx.formParam("weather")` enum string — "clear" | "rain" | "thunder" —
+   * not separate storm/thundering booleans.
+   */
   setWeather(uuid, weather) {
     return this.http.request("POST", `worlds/${encodeURIComponent(uuid)}/weather`, {
-      body: weather
+      body: { weather },
+      form: true
     });
   }
   /** Get entity counts within a specific world. */
@@ -456,11 +526,15 @@ var PluginsModule = class {
     return this.http.request("GET", "plugins");
   }
   /**
-   * Install a plugin from a URL or identifier.
+   * Install a plugin by downloading it from a direct URL.
    * This is a privileged endpoint — requires a write-enabled API key.
+   *
+   * Server-side (`PluginApi.installPlugin`) reads
+   * `ctx.formParam("downloadUrl")`, not "source", and the request must be
+   * form-urlencoded.
    */
-  install(source) {
-    return this.http.request("POST", "plugins", { body: { source } });
+  install(downloadUrl) {
+    return this.http.request("POST", "plugins", { body: { downloadUrl }, form: true });
   }
   /** Enable a plugin by name. */
   enable(name) {
@@ -489,12 +563,18 @@ var PlaceholdersModule = class {
   }
   http;
   /**
-   * Replace PlaceholderAPI-style placeholders (e.g. "%player_name%") for a
-   * player, returning the resolved string.
+   * Replace PlaceholderAPI-style placeholders (e.g. "%player_name%") in
+   * `message` for a player, returning the resolved string.
+   *
+   * Server-side this is `PAPIApi.replacePlaceholders`, which reads
+   * `ctx.formParam("message")` and `ctx.formParam("uuid")` — the field is
+   * literally named "message", not "text", and the whole body must be
+   * form-urlencoded.
    */
-  replace(uuid, text) {
+  replace(uuid, message) {
     return this.http.request("POST", "placeholders/replace", {
-      body: { uuid, text }
+      body: { uuid, message },
+      form: true
     });
   }
 };
@@ -585,9 +665,35 @@ var NoxAuthModule = class {
   }
 };
 
+// src/modules/skills.ts
+var SkillsModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Get mcMMO skill levels and power level for a player.
+   * Only works for **online** players — mcMMO's public ExperienceAPI has
+   * no offline lookup, so this throws `NoxAeApiNotFoundError` if the
+   * player isn't currently connected, and `NoxAeApiServerError` (503)
+   * if mcMMO isn't loaded on the target server.
+   */
+  getMcmmoSkills(uuid) {
+    return this.http.request("GET", `skills/mcmmo/player/${encodeURIComponent(uuid)}`);
+  }
+  /**
+   * Get AuraSkills skill levels and power level for a player.
+   * Works for offline players. Throws `NoxAeApiServerError` (503) if
+   * AuraSkills isn't loaded on the target server.
+   */
+  getAuraSkills(uuid) {
+    return this.http.request("GET", `skills/auraskills/player/${encodeURIComponent(uuid)}`);
+  }
+};
+
 // src/socket.ts
 function toWsUrl(baseUrl, route, apiKey) {
-  const url = new URL(`${baseUrl.replace(/\/+$/, "")}/${route.replace(/^\/+/, "")}`);
+  const url = new URL(`${baseUrl.replace(/\/+$/, "")}/v1/ws/${route.replace(/^\/+/, "")}`);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
   if (apiKey) url.searchParams.set("key", apiKey);
   return url.toString();
@@ -690,6 +796,8 @@ var NoxAeApiClient = class _NoxAeApiClient {
   luckperms;
   /** Only works if `noxauth.enabled: true` is set in the server config. */
   noxauth;
+  /** Requires mcMMO and/or AuraSkills to be loaded on the target server. */
+  skills;
   http;
   baseUrl;
   apiKey;
@@ -706,6 +814,7 @@ var NoxAeApiClient = class _NoxAeApiClient {
     this.placeholders = new PlaceholdersModule(this.http);
     this.luckperms = new LuckPermsModule(this.http);
     this.noxauth = new NoxAuthModule(this.http);
+    this.skills = new SkillsModule(this.http);
   }
   /**
    * Build a client from environment variables: