@wumx-labs/noxaeapi-sdk 0.4.0 → 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;
@@ -313,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. */
@@ -644,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;
@@ -652,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>;
 }
 
 /**
@@ -940,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 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 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;
@@ -313,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. */
@@ -644,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;
@@ -652,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>;
 }
 
 /**
@@ -940,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 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 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.js

@@ -248,6 +248,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(
@@ -775,6 +787,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