@wumx-labs/noxaeapi-sdk 0.3.5 → 0.4.1

package/README.md

@@ -30,6 +30,11 @@ await client.server.broadcast("Hello from the SDK!");
 const coins = await client.economy.getCurrencyBalance("coins", players[0].uuid);
 const top = await client.leaderboards.getTop("mcmmo-power", 10);
 const network = await client.network.statusAll();
+
+// Resolve a name to a UUID, then get their one-call profile (identity,
+// ban/whitelist status, Vault balance, and every leaderboard entry at once):
+const { uuid } = await client.players.resolve("NoxlyDev");
+const profile = await client.leaderboards.getPlayerProfile(uuid);
 ```
 
 ### From environment variables
@@ -109,6 +114,47 @@ Some modules only work depending on the target server's setup:
 
 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
+`statusAll()`/`statusById()` instead).
+
+```ts
+import { NoxAeApiNetworkHubClient } from "@wumx-labs/noxaeapi-sdk";
+
+const hub = new NoxAeApiNetworkHubClient({
+  baseUrl: "http://localhost:9090", // the hub's api-port, not a backend's port
+  apiKey: "your-hub-key",
+});
+
+const status = await hub.network.statusAll();
+const players = await hub.network.players();
+const found = await hub.network.findPlayer(players.players[0]?.uuid ?? "");
+await hub.network.broadcast("Hello from the hub!");
+
+// Reach a specific backend's own REST routes through the hub:
+await 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.fromEnv()`'s `NOXAEAPI_*` vars so a
+process can hold both clients at once):
+
+```ts
+const hub = NoxAeApiNetworkHubClient.fromEnv();
+```
+
 ## Configuration
 
 ```ts

package/dist/index.cjs

@@ -250,6 +250,18 @@ var PlayersModule = class {
   get(uuid) {
     return this.http.request("GET", `players/${encodeURIComponent(uuid)}`);
   }
+  /**
+   * Resolve a player name to their UUID using the server's own local player
+   * cache (works on both online-mode and offline-mode servers, unlike
+   * Mojang's public API - the UUID returned matches whatever this server
+   * actually uses for that player's stats/economy/etc). Checks currently
+   * online players first, then falls back to the server's offline player
+   * cache. Throws `NoxAeApiNotFoundError` if no known player with that name
+   * has ever joined.
+   */
+  resolve(name) {
+    return this.http.request("GET", `players/resolve/${encodeURIComponent(name)}`);
+  }
   /** Get a player's inventory in a specific world. */
   getInventory(playerUuid, worldUuid) {
     return this.http.request(
@@ -777,6 +789,39 @@ var LeaderboardModule = class {
       query: { limit }
     });
   }
+  /**
+   * One-call player profile: identity, whitelist/ban status, Vault balance,
+   * and this player's entry in every registered leaderboard source. Built so
+   * clients never have to know how many leaderboard sources exist or scan
+   * top-N lists themselves.
+   *
+   * Throws `NoxAeApiNotFoundError` if no known player with that UUID has
+   * ever joined.
+   */
+  getPlayerProfile(uuid) {
+    return this.http.request("GET", `players/${encodeURIComponent(uuid)}/profile`);
+  }
+  /**
+   * Bulk player profiles — same shape as `getPlayerProfile`, for many
+   * players at once. Computes each leaderboard source's full ranking
+   * exactly once for the whole batch rather than once per player, so this
+   * is far cheaper than calling `getPlayerProfile` in a loop.
+   *
+   * Pass `uuids` to fetch an exact, specific set of players — unknown UUIDs
+   * are silently skipped rather than throwing. Omit `uuids` to page through
+   * every known player instead, using `page`/`limit`, optionally narrowed
+   * to only currently-online players via `onlineOnly`.
+   */
+  getPlayerProfiles(opts = {}) {
+    return this.http.request("GET", "players/profiles", {
+      query: {
+        uuids: opts.uuids?.length ? opts.uuids.join(",") : void 0,
+        page: opts.page,
+        limit: opts.limit,
+        onlineOnly: opts.onlineOnly
+      }
+    });
+  }
 };
 
 // src/modules/network.ts
@@ -830,6 +875,59 @@ var NetworkModule = class {
   }
 };
 
+// src/modules/network-hub.ts
+var NetworkHubModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Get last-known status (from the registry) for every backend node that has ever registered. */
+  statusAll() {
+    return this.http.request("GET", "network/status");
+  }
+  /** Get last-known status for a single node by its configured ID. */
+  statusById(id) {
+    return this.http.request("GET", `network/status/${encodeURIComponent(id)}`);
+  }
+  /**
+   * List every player currently connected to the proxy, read straight from
+   * Velocity's own player registry (not reported by backends), along with
+   * which backend server each is on.
+   */
+  players() {
+    return this.http.request("GET", "network/players");
+  }
+  /** Find which backend server a player is currently on by UUID (proxy-authoritative). */
+  findPlayer(uuid) {
+    return this.http.request("GET", `network/players/${encodeURIComponent(uuid)}`);
+  }
+  /**
+   * Broadcast a message directly to every player connected to the proxy.
+   * Unlike `NetworkModule.broadcast`, this doesn't forward to each
+   * backend's `/v1/chat/broadcast` — the proxy already has every player
+   * in hand — so it still delivers even to servers with no REST API of
+   * their own reachable from the hub.
+   */
+  broadcast(message) {
+    return this.http.request("POST", "network/broadcast", { body: { message }, form: true });
+  }
+  /**
+   * Forward an arbitrary request to a specific backend node's own REST
+   * API, e.g. `hub.forward("survival", "POST", "server/exec", { body:
+   * { command: "say hi" }, form: true })` reaches that backend's
+   * `POST /v1/server/exec` directly. Useful for endpoints the hub doesn't
+   * have a dedicated method for (economy, worlds, etc) without
+   * instantiating a second client pointed at that backend directly.
+   *
+   * The target backend responds according to its own route's expected
+   * encoding (form vs JSON) — pass `form: true` the same way you would for
+   * a direct call to that endpoint.
+   */
+  forward(id, method, path, opts = {}) {
+    return this.http.request(method, `network/${encodeURIComponent(id)}/${path.replace(/^\/+/, "")}`, opts);
+  }
+};
+
 // src/socket.ts
 function toWsUrl(baseUrl, route, apiKey) {
   const url = new URL(`${baseUrl.replace(/\/+$/, "")}/v1/ws/${route.replace(/^\/+/, "")}`);
@@ -939,7 +1037,17 @@ var NoxAeApiClient = class _NoxAeApiClient {
   skills;
   /** Generic ranked leaderboards (economy currencies, mcMMO, AuraSkills, ...). */
   leaderboards;
-  /** Only works if `network.enabled: true` is set in the server config. */
+  /**
+   * 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
+   * `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.
+   */
   network;
   http;
   baseUrl;
@@ -990,11 +1098,39 @@ var NoxAeApiClient = class _NoxAeApiClient {
     });
   }
 };
+var NoxAeApiNetworkHubClient = class _NoxAeApiNetworkHubClient {
+  /** The network hub's aggregated view of every registered backend node. */
+  network;
+  constructor(options) {
+    const http = new HttpEngine(options);
+    this.network = new NetworkHubModule(http);
+  }
+  /**
+   * Build a hub client from environment variables:
+   * `NOXAEAPI_HUB_BASE_URL` and `NOXAEAPI_HUB_KEY`.
+   *
+   * Same convenience as `NoxAeApiClient.fromEnv()`, under separate env var
+   * names so a process can hold both a backend client and a hub client at
+   * once without the two colliding.
+   */
+  static fromEnv(overrides = {}) {
+    const env = globalThis.process?.env;
+    const baseUrl = overrides.baseUrl ?? env?.NOXAEAPI_HUB_BASE_URL;
+    const apiKey = overrides.apiKey ?? env?.NOXAEAPI_HUB_KEY;
+    if (!baseUrl) {
+      throw new Error(
+        "NoxAeApiNetworkHubClient.fromEnv(): NOXAEAPI_HUB_BASE_URL is not set and no baseUrl override was given."
+      );
+    }
+    return new _NoxAeApiNetworkHubClient({ ...overrides, baseUrl, apiKey });
+  }
+};
 
 exports.NoxAeApiClient = NoxAeApiClient;
 exports.NoxAeApiError = NoxAeApiError;
 exports.NoxAeApiForbiddenError = NoxAeApiForbiddenError;
 exports.NoxAeApiNetworkError = NoxAeApiNetworkError;
+exports.NoxAeApiNetworkHubClient = NoxAeApiNetworkHubClient;
 exports.NoxAeApiNotFoundError = NoxAeApiNotFoundError;
 exports.NoxAeApiRateLimitError = NoxAeApiRateLimitError;
 exports.NoxAeApiServerError = NoxAeApiServerError;