@wumx-labs/noxaeapi-sdk 0.3.5 → 0.4.1

package/dist/index.d.cts

@@ -77,6 +77,11 @@ interface OfflinePlayer {
     balance: number | null;
     lastPlayed: number;
 }
+/** Result of resolving a player name to their UUID via `GET /players/resolve/{name}`. */
+interface PlayerResolveResult {
+    name: string;
+    uuid: string;
+}
 interface ServerHealth {
     cpus: number;
     uptime: number;
@@ -234,6 +239,61 @@ interface LeaderboardEntry {
     value: number;
     [key: string]: unknown;
 }
+/** Ban details for a player, as reported by `GET /v1/players/{uuid}/profile`'s `status.ban`. */
+interface PlayerProfileBan {
+    banned: boolean;
+    /** Only present when `banned` is true. */
+    reason?: string;
+    /** Only present when `banned` is true. */
+    source?: string;
+    /** Only present when `banned` is true. Serialized server-side as a locale-formatted date string, not ISO-8601. */
+    created?: string;
+    /** Only present when `banned` is true. `null`/absent means a permanent ban. Same date-string format as `created`. */
+    expires?: string | null;
+}
+/** Whitelist + ban status for a player, as reported by `GET /v1/players/{uuid}/profile`'s `status` field. */
+interface PlayerProfileStatus {
+    whitelisted: boolean;
+    ban: PlayerProfileBan;
+}
+/**
+ * Vault economy info for a player, as reported by `GET /v1/players/{uuid}/profile`'s `economy`
+ * field. Single-currency (Vault), not ExcellentEconomy's multi-currency system - see
+ * `EconomyModule.getCurrencyBalance` for that.
+ */
+interface PlayerProfileEconomy {
+    available: boolean;
+    /** Only present when `available` is true. */
+    balance?: number;
+}
+/** One leaderboard source's contribution to a player profile's `stats` array. */
+interface PlayerProfileStatTile {
+    id: string;
+    label: string;
+    status: "ranked" | "not_ranked" | "unavailable";
+    /** Only present when `status` is "ranked". */
+    value?: number;
+    /** Only present when `status` is "ranked" and the source reports a positive rank. */
+    rank?: number;
+}
+/**
+ * One-call player profile combining identity, whitelist/ban status, Vault balance, and this
+ * player's entry in every registered leaderboard source. Returned by
+ * `GET /v1/players/{uuid}/profile` and (as the `players` array) by `GET /v1/players/profiles`.
+ */
+interface PlayerProfile {
+    name: string | null;
+    uuid: string;
+    online: boolean;
+    status: PlayerProfileStatus;
+    economy: PlayerProfileEconomy;
+    stats: PlayerProfileStatTile[];
+}
+/** Response shape of `GET /v1/players/profiles` (bulk player profiles). */
+interface PlayerProfilesResponse {
+    count: number;
+    players: PlayerProfile[];
+}
 interface NetworkServerStatus {
     id: string;
     label: string;
@@ -268,6 +328,41 @@ interface NetworkHealthResponse {
 }
 /** Per-server "success" | "error" result, keyed by network server ID. */
 type NetworkBroadcastResponse = Record<string, "success" | "error">;
+/** Last-known state of one backend node, as tracked by the network hub. */
+interface NetworkHubNode {
+    id: string;
+    label: string;
+    online: boolean;
+    tps: string;
+    onlinePlayers: number;
+    maxPlayers: number;
+    /** Opaque payload the backend reported in its last heartbeat. Shape isn't fixed by the hub. */
+    health: unknown;
+    /** Unix epoch ms of the last heartbeat received, or 0 if never. */
+    lastHeartbeatAt: number;
+}
+interface NetworkHubStatusResponse {
+    network: NetworkHubNode[];
+}
+/** A player as seen directly by the proxy (not reported by a backend). */
+interface NetworkHubPlayer {
+    uuid: string;
+    name: string;
+    /** Backend server ID the player is currently connected to, if known. */
+    server?: string;
+}
+interface NetworkHubPlayersResponse {
+    total: number;
+    players: NetworkHubPlayer[];
+}
+interface NetworkHubFindPlayerResponse {
+    found: boolean;
+    player?: NetworkHubPlayer;
+}
+/** Result of a proxy-wide broadcast: how many connected players received the message. */
+interface NetworkHubBroadcastResponse {
+    delivered: number;
+}
 
 declare class PlayersModule {
     private readonly http;
@@ -278,6 +373,16 @@ declare class PlayersModule {
     listAll(): Promise<OfflinePlayer[]>;
     /** Get a single player by UUID (works for online or offline players). */
     get(uuid: string): Promise<OnlinePlayer | OfflinePlayer>;
+    /**
+     * 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: string): Promise<PlayerResolveResult>;
     /** Get a player's inventory in a specific world. */
     getInventory(playerUuid: string, worldUuid: string): Promise<InventoryItem[]>;
     /** Kick an online player, optionally with a reason. */
@@ -609,6 +714,10 @@ declare class SkillsModule {
  * (e.g. the backing plugin isn't loaded) throw `NoxAeApiError` with the
  * source's own unavailable status (424 for economy currencies, 503 for
  * mcMMO/AuraSkills) when you call `getTop`.
+ *
+ * This module also wraps the player-profile routes (`/v1/players/{uuid}/profile`
+ * and `/v1/players/profiles`), which live server-side alongside the
+ * leaderboard sources since they're built on top of them.
  */
 declare class LeaderboardModule {
     private readonly http;
@@ -617,6 +726,33 @@ declare class LeaderboardModule {
     list(): Promise<LeaderboardSourceInfo[]>;
     /** Get ranked entries for one leaderboard source (see `list()` for valid IDs). */
     getTop(id: string, limit?: number): Promise<LeaderboardEntry[]>;
+    /**
+     * 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: string): Promise<PlayerProfile>;
+    /**
+     * 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?: {
+        uuids?: string[];
+        page?: number;
+        limit?: number;
+        onlineOnly?: boolean;
+    }): Promise<PlayerProfilesResponse>;
 }
 
 /**
@@ -670,6 +806,69 @@ declare class NetworkModule {
     }): Promise<T>;
 }
 
+/**
+ * Wraps the `/v1/network/*` routes exposed by the **NoxAeApi-Velocity**
+ * network hub — a separate plugin/process from NoxAeApi-main, run on the
+ * Velocity proxy and listening on its own port (`NetworkHubConfig`'s
+ * `api-port`, distinct from any individual backend's own REST port).
+ *
+ * Point a `NoxAeApiNetworkHubClient` (not the regular `NoxAeApiClient`) at
+ * that port to use this module. Backend Paper/Bukkit servers connect out
+ * to the hub over WebSocket (`/network/register`) and push register /
+ * heartbeat / player-join / player-quit events; the hub answers every
+ * method below from its own in-memory registry, so calls here are cheap
+ * and don't block on a live round trip to each backend the way the older
+ * `NetworkModule` (NoxAeApi-main's built-in aggregator) does.
+ *
+ * Response shapes differ from `NetworkModule` even where the route names
+ * match — e.g. `players()` returns one flat proxy-wide player list here,
+ * not a per-server breakdown — so the two modules' types aren't
+ * interchangeable. There's also no hub equivalent of `/v1/network/health`;
+ * each node's last-reported health is embedded in `status*()`'s
+ * `NetworkHubNode.health` field instead.
+ */
+declare class NetworkHubModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Get last-known status (from the registry) for every backend node that has ever registered. */
+    statusAll(): Promise<NetworkHubStatusResponse>;
+    /** Get last-known status for a single node by its configured ID. */
+    statusById(id: string): Promise<NetworkHubNode>;
+    /**
+     * 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(): Promise<NetworkHubPlayersResponse>;
+    /** Find which backend server a player is currently on by UUID (proxy-authoritative). */
+    findPlayer(uuid: string): Promise<NetworkHubFindPlayerResponse>;
+    /**
+     * 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: string): Promise<NetworkHubBroadcastResponse>;
+    /**
+     * 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<T = unknown>(id: string, method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH", path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, QueryValue>;
+        form?: boolean;
+    }): Promise<T>;
+}
+
 type NoxAeApiWsEvent = "open" | "close" | "error" | "console" | "event" | "message";
 type Listener = (payload: unknown) => void;
 interface NoxAeApiWsOptions {
@@ -733,7 +932,17 @@ declare class NoxAeApiClient {
     readonly skills: SkillsModule;
     /** Generic ranked leaderboards (economy currencies, mcMMO, AuraSkills, ...). */
     readonly leaderboards: LeaderboardModule;
-    /** 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.
+     */
     readonly network: NetworkModule;
     private readonly http;
     private readonly baseUrl;
@@ -752,6 +961,33 @@ declare class NoxAeApiClient {
     /** Open a WebSocket connection to the server (console tail or event stream). */
     connect(options?: Partial<NoxAeApiWsOptions>): NoxAeApiSocket;
 }
+/**
+ * Client for the **NoxAeApi-Velocity** network hub — a separate plugin
+ * that runs on the Velocity proxy, not on any individual backend server.
+ * Point `baseUrl` at the hub's own REST port (`NetworkHubConfig`'s
+ * `api-port`), not a backend's port, and use `NOXAEAPI_HUB_*` env vars
+ * (via `fromEnv`) 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 `NoxAeApiClient`
+ * does. To reach a specific backend's own routes through the hub, use
+ * `hub.network.forward(id, ...)`.
+ */
+declare class NoxAeApiNetworkHubClient {
+    /** The network hub's aggregated view of every registered backend node. */
+    readonly network: NetworkHubModule;
+    constructor(options: NoxAeApiClientOptions);
+    /**
+     * 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?: Partial<NoxAeApiClientOptions>): NoxAeApiNetworkHubClient;
+}
 
 interface NoxAeApiErrorInfo {
     status: number;
@@ -805,4 +1041,4 @@ declare class NoxAeApiNetworkError extends Error {
     constructor(message: string, method: string, path: string, cause?: unknown);
 }
 
-export { type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type NetworkBroadcastResponse, type NetworkFindPlayerResponse, type NetworkHealthResponse, type NetworkHealthServerEntry, type NetworkPlayersResponse, type NetworkPlayersServerEntry, type NetworkServerStatus, NoxAeApiClient, type NoxAeApiClientOptions, NoxAeApiError, NoxAeApiForbiddenError, NoxAeApiNetworkError, NoxAeApiNotFoundError, NoxAeApiRateLimitError, NoxAeApiServerError, NoxAeApiSocket, NoxAeApiUnauthorizedError, type NoxAeApiWsEvent, type NoxAeApiWsOptions, type NoxAuthPlayerInfo, type Objective, type OfflinePlayer, type OnlinePlayer, type PasswordCheckResult, type PermissionNode, type PlayerBalance, type PlayerStats, type Plugin, type RetryOptions, type Score, type Scoreboard, type ServerBan, type ServerHealth, type ServerInfo, type SkillInfo, type TopBalanceEntry, type WhitelistEntry, type World };
+export { type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type NetworkBroadcastResponse, type NetworkFindPlayerResponse, type NetworkHealthResponse, type NetworkHealthServerEntry, type NetworkHubBroadcastResponse, type NetworkHubFindPlayerResponse, type NetworkHubNode, type NetworkHubPlayer, type NetworkHubPlayersResponse, type NetworkHubStatusResponse, type NetworkPlayersResponse, type NetworkPlayersServerEntry, type NetworkServerStatus, NoxAeApiClient, type NoxAeApiClientOptions, NoxAeApiError, NoxAeApiForbiddenError, NoxAeApiNetworkError, NoxAeApiNetworkHubClient, NoxAeApiNotFoundError, NoxAeApiRateLimitError, NoxAeApiServerError, NoxAeApiSocket, NoxAeApiUnauthorizedError, type NoxAeApiWsEvent, type NoxAeApiWsOptions, type NoxAuthPlayerInfo, type Objective, type OfflinePlayer, type OnlinePlayer, type PasswordCheckResult, type PermissionNode, type PlayerBalance, type PlayerProfile, type PlayerProfileBan, type PlayerProfileEconomy, type PlayerProfileStatTile, type PlayerProfileStatus, type PlayerProfilesResponse, type PlayerResolveResult, type PlayerStats, type Plugin, type RetryOptions, type Score, type Scoreboard, type ServerBan, type ServerHealth, type ServerInfo, type SkillInfo, type TopBalanceEntry, type WhitelistEntry, type World };

package/dist/index.d.ts

@@ -77,6 +77,11 @@ interface OfflinePlayer {
     balance: number | null;
     lastPlayed: number;
 }
+/** Result of resolving a player name to their UUID via `GET /players/resolve/{name}`. */
+interface PlayerResolveResult {
+    name: string;
+    uuid: string;
+}
 interface ServerHealth {
     cpus: number;
     uptime: number;
@@ -234,6 +239,61 @@ interface LeaderboardEntry {
     value: number;
     [key: string]: unknown;
 }
+/** Ban details for a player, as reported by `GET /v1/players/{uuid}/profile`'s `status.ban`. */
+interface PlayerProfileBan {
+    banned: boolean;
+    /** Only present when `banned` is true. */
+    reason?: string;
+    /** Only present when `banned` is true. */
+    source?: string;
+    /** Only present when `banned` is true. Serialized server-side as a locale-formatted date string, not ISO-8601. */
+    created?: string;
+    /** Only present when `banned` is true. `null`/absent means a permanent ban. Same date-string format as `created`. */
+    expires?: string | null;
+}
+/** Whitelist + ban status for a player, as reported by `GET /v1/players/{uuid}/profile`'s `status` field. */
+interface PlayerProfileStatus {
+    whitelisted: boolean;
+    ban: PlayerProfileBan;
+}
+/**
+ * Vault economy info for a player, as reported by `GET /v1/players/{uuid}/profile`'s `economy`
+ * field. Single-currency (Vault), not ExcellentEconomy's multi-currency system - see
+ * `EconomyModule.getCurrencyBalance` for that.
+ */
+interface PlayerProfileEconomy {
+    available: boolean;
+    /** Only present when `available` is true. */
+    balance?: number;
+}
+/** One leaderboard source's contribution to a player profile's `stats` array. */
+interface PlayerProfileStatTile {
+    id: string;
+    label: string;
+    status: "ranked" | "not_ranked" | "unavailable";
+    /** Only present when `status` is "ranked". */
+    value?: number;
+    /** Only present when `status` is "ranked" and the source reports a positive rank. */
+    rank?: number;
+}
+/**
+ * One-call player profile combining identity, whitelist/ban status, Vault balance, and this
+ * player's entry in every registered leaderboard source. Returned by
+ * `GET /v1/players/{uuid}/profile` and (as the `players` array) by `GET /v1/players/profiles`.
+ */
+interface PlayerProfile {
+    name: string | null;
+    uuid: string;
+    online: boolean;
+    status: PlayerProfileStatus;
+    economy: PlayerProfileEconomy;
+    stats: PlayerProfileStatTile[];
+}
+/** Response shape of `GET /v1/players/profiles` (bulk player profiles). */
+interface PlayerProfilesResponse {
+    count: number;
+    players: PlayerProfile[];
+}
 interface NetworkServerStatus {
     id: string;
     label: string;
@@ -268,6 +328,41 @@ interface NetworkHealthResponse {
 }
 /** Per-server "success" | "error" result, keyed by network server ID. */
 type NetworkBroadcastResponse = Record<string, "success" | "error">;
+/** Last-known state of one backend node, as tracked by the network hub. */
+interface NetworkHubNode {
+    id: string;
+    label: string;
+    online: boolean;
+    tps: string;
+    onlinePlayers: number;
+    maxPlayers: number;
+    /** Opaque payload the backend reported in its last heartbeat. Shape isn't fixed by the hub. */
+    health: unknown;
+    /** Unix epoch ms of the last heartbeat received, or 0 if never. */
+    lastHeartbeatAt: number;
+}
+interface NetworkHubStatusResponse {
+    network: NetworkHubNode[];
+}
+/** A player as seen directly by the proxy (not reported by a backend). */
+interface NetworkHubPlayer {
+    uuid: string;
+    name: string;
+    /** Backend server ID the player is currently connected to, if known. */
+    server?: string;
+}
+interface NetworkHubPlayersResponse {
+    total: number;
+    players: NetworkHubPlayer[];
+}
+interface NetworkHubFindPlayerResponse {
+    found: boolean;
+    player?: NetworkHubPlayer;
+}
+/** Result of a proxy-wide broadcast: how many connected players received the message. */
+interface NetworkHubBroadcastResponse {
+    delivered: number;
+}
 
 declare class PlayersModule {
     private readonly http;
@@ -278,6 +373,16 @@ declare class PlayersModule {
     listAll(): Promise<OfflinePlayer[]>;
     /** Get a single player by UUID (works for online or offline players). */
     get(uuid: string): Promise<OnlinePlayer | OfflinePlayer>;
+    /**
+     * 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: string): Promise<PlayerResolveResult>;
     /** Get a player's inventory in a specific world. */
     getInventory(playerUuid: string, worldUuid: string): Promise<InventoryItem[]>;
     /** Kick an online player, optionally with a reason. */
@@ -609,6 +714,10 @@ declare class SkillsModule {
  * (e.g. the backing plugin isn't loaded) throw `NoxAeApiError` with the
  * source's own unavailable status (424 for economy currencies, 503 for
  * mcMMO/AuraSkills) when you call `getTop`.
+ *
+ * This module also wraps the player-profile routes (`/v1/players/{uuid}/profile`
+ * and `/v1/players/profiles`), which live server-side alongside the
+ * leaderboard sources since they're built on top of them.
  */
 declare class LeaderboardModule {
     private readonly http;
@@ -617,6 +726,33 @@ declare class LeaderboardModule {
     list(): Promise<LeaderboardSourceInfo[]>;
     /** Get ranked entries for one leaderboard source (see `list()` for valid IDs). */
     getTop(id: string, limit?: number): Promise<LeaderboardEntry[]>;
+    /**
+     * 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: string): Promise<PlayerProfile>;
+    /**
+     * 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?: {
+        uuids?: string[];
+        page?: number;
+        limit?: number;
+        onlineOnly?: boolean;
+    }): Promise<PlayerProfilesResponse>;
 }
 
 /**
@@ -670,6 +806,69 @@ declare class NetworkModule {
     }): Promise<T>;
 }
 
+/**
+ * Wraps the `/v1/network/*` routes exposed by the **NoxAeApi-Velocity**
+ * network hub — a separate plugin/process from NoxAeApi-main, run on the
+ * Velocity proxy and listening on its own port (`NetworkHubConfig`'s
+ * `api-port`, distinct from any individual backend's own REST port).
+ *
+ * Point a `NoxAeApiNetworkHubClient` (not the regular `NoxAeApiClient`) at
+ * that port to use this module. Backend Paper/Bukkit servers connect out
+ * to the hub over WebSocket (`/network/register`) and push register /
+ * heartbeat / player-join / player-quit events; the hub answers every
+ * method below from its own in-memory registry, so calls here are cheap
+ * and don't block on a live round trip to each backend the way the older
+ * `NetworkModule` (NoxAeApi-main's built-in aggregator) does.
+ *
+ * Response shapes differ from `NetworkModule` even where the route names
+ * match — e.g. `players()` returns one flat proxy-wide player list here,
+ * not a per-server breakdown — so the two modules' types aren't
+ * interchangeable. There's also no hub equivalent of `/v1/network/health`;
+ * each node's last-reported health is embedded in `status*()`'s
+ * `NetworkHubNode.health` field instead.
+ */
+declare class NetworkHubModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Get last-known status (from the registry) for every backend node that has ever registered. */
+    statusAll(): Promise<NetworkHubStatusResponse>;
+    /** Get last-known status for a single node by its configured ID. */
+    statusById(id: string): Promise<NetworkHubNode>;
+    /**
+     * 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(): Promise<NetworkHubPlayersResponse>;
+    /** Find which backend server a player is currently on by UUID (proxy-authoritative). */
+    findPlayer(uuid: string): Promise<NetworkHubFindPlayerResponse>;
+    /**
+     * 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: string): Promise<NetworkHubBroadcastResponse>;
+    /**
+     * 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<T = unknown>(id: string, method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH", path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, QueryValue>;
+        form?: boolean;
+    }): Promise<T>;
+}
+
 type NoxAeApiWsEvent = "open" | "close" | "error" | "console" | "event" | "message";
 type Listener = (payload: unknown) => void;
 interface NoxAeApiWsOptions {
@@ -733,7 +932,17 @@ declare class NoxAeApiClient {
     readonly skills: SkillsModule;
     /** Generic ranked leaderboards (economy currencies, mcMMO, AuraSkills, ...). */
     readonly leaderboards: LeaderboardModule;
-    /** 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.
+     */
     readonly network: NetworkModule;
     private readonly http;
     private readonly baseUrl;
@@ -752,6 +961,33 @@ declare class NoxAeApiClient {
     /** Open a WebSocket connection to the server (console tail or event stream). */
     connect(options?: Partial<NoxAeApiWsOptions>): NoxAeApiSocket;
 }
+/**
+ * Client for the **NoxAeApi-Velocity** network hub — a separate plugin
+ * that runs on the Velocity proxy, not on any individual backend server.
+ * Point `baseUrl` at the hub's own REST port (`NetworkHubConfig`'s
+ * `api-port`), not a backend's port, and use `NOXAEAPI_HUB_*` env vars
+ * (via `fromEnv`) 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 `NoxAeApiClient`
+ * does. To reach a specific backend's own routes through the hub, use
+ * `hub.network.forward(id, ...)`.
+ */
+declare class NoxAeApiNetworkHubClient {
+    /** The network hub's aggregated view of every registered backend node. */
+    readonly network: NetworkHubModule;
+    constructor(options: NoxAeApiClientOptions);
+    /**
+     * 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?: Partial<NoxAeApiClientOptions>): NoxAeApiNetworkHubClient;
+}
 
 interface NoxAeApiErrorInfo {
     status: number;
@@ -805,4 +1041,4 @@ declare class NoxAeApiNetworkError extends Error {
     constructor(message: string, method: string, path: string, cause?: unknown);
 }
 
-export { type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type NetworkBroadcastResponse, type NetworkFindPlayerResponse, type NetworkHealthResponse, type NetworkHealthServerEntry, type NetworkPlayersResponse, type NetworkPlayersServerEntry, type NetworkServerStatus, NoxAeApiClient, type NoxAeApiClientOptions, NoxAeApiError, NoxAeApiForbiddenError, NoxAeApiNetworkError, NoxAeApiNotFoundError, NoxAeApiRateLimitError, NoxAeApiServerError, NoxAeApiSocket, NoxAeApiUnauthorizedError, type NoxAeApiWsEvent, type NoxAeApiWsOptions, type NoxAuthPlayerInfo, type Objective, type OfflinePlayer, type OnlinePlayer, type PasswordCheckResult, type PermissionNode, type PlayerBalance, type PlayerStats, type Plugin, type RetryOptions, type Score, type Scoreboard, type ServerBan, type ServerHealth, type ServerInfo, type SkillInfo, type TopBalanceEntry, type WhitelistEntry, type World };
+export { type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type NetworkBroadcastResponse, type NetworkFindPlayerResponse, type NetworkHealthResponse, type NetworkHealthServerEntry, type NetworkHubBroadcastResponse, type NetworkHubFindPlayerResponse, type NetworkHubNode, type NetworkHubPlayer, type NetworkHubPlayersResponse, type NetworkHubStatusResponse, type NetworkPlayersResponse, type NetworkPlayersServerEntry, type NetworkServerStatus, NoxAeApiClient, type NoxAeApiClientOptions, NoxAeApiError, NoxAeApiForbiddenError, NoxAeApiNetworkError, NoxAeApiNetworkHubClient, NoxAeApiNotFoundError, NoxAeApiRateLimitError, NoxAeApiServerError, NoxAeApiSocket, NoxAeApiUnauthorizedError, type NoxAeApiWsEvent, type NoxAeApiWsOptions, type NoxAuthPlayerInfo, type Objective, type OfflinePlayer, type OnlinePlayer, type PasswordCheckResult, type PermissionNode, type PlayerBalance, type PlayerProfile, type PlayerProfileBan, type PlayerProfileEconomy, type PlayerProfileStatTile, type PlayerProfileStatus, type PlayerProfilesResponse, type PlayerResolveResult, type PlayerStats, type Plugin, type RetryOptions, type Score, type Scoreboard, type ServerBan, type ServerHealth, type ServerInfo, type SkillInfo, type TopBalanceEntry, type WhitelistEntry, type World };