@wumx-labs/noxaeapi-sdk 0.4.2 → 0.5.1

package/dist/index.d.cts

@@ -82,6 +82,19 @@ interface PlayerResolveResult {
     name: string;
     uuid: string;
 }
+interface IdentityServerInfo {
+    id: string;
+    label: string;
+}
+/** Result of resolving player identity via `GET /v1/identity/{name}`. */
+interface IdentityInfo {
+    username: string;
+    identityUuid: string;
+    localUuid: string | null;
+    server: IdentityServerInfo;
+    onlineMode: boolean;
+    hasPlayedBefore: boolean;
+}
 interface ServerHealth {
     cpus: number;
     uptime: number;
@@ -168,16 +181,67 @@ interface TopBalanceEntry {
     uuid: string;
     balance: number;
 }
-interface GroupInfo {
-    name: string;
-    permissions: string[];
-}
+/** A single LuckPerms node (permission, inheritance, prefix, etc.) as returned by the server. */
 interface PermissionNode {
     permission: string;
     value: boolean;
+    /** Epoch seconds, or `0` for a permanent (non-expiring) node. */
     expiry: number;
-    server: string | null;
-    world: string | null;
+    /** Server context this node applies to, or the literal `"global"` if none was set. */
+    server: string;
+    /** World context this node applies to, or the literal `"global"` if none was set. */
+    world: string;
+}
+interface GroupInfo {
+    name: string;
+    /** `null` if the group has no display name node set. */
+    displayName: string | null;
+    weight: number;
+    permissions: PermissionNode[];
+}
+/** A player's or group's resolved prefix, suffix, and custom meta key-values. */
+interface MetaInfo {
+    prefix: string | null;
+    suffix: string | null;
+    /** LuckPerms keeps every value ever set per key; the highest-priority one wins in-game. */
+    meta: Record<string, string[]>;
+}
+/** A LuckPerms track (an ordered rank ladder used for promote/demote). */
+interface TrackInfo {
+    name: string;
+    /** Ordered from lowest to highest rank. */
+    groups: string[];
+}
+/** Optional server/world context that scopes a node to a subset of the network. */
+interface LuckPermsContextOptions {
+    /** e.g. `"survival"` — matches LuckPerms' `server` context key. */
+    server?: string;
+    /** e.g. `"world_nether"` — matches LuckPerms' `world` context key. */
+    world?: string;
+}
+interface LuckPermsCheckPermissionResult {
+    uuid: string;
+    permission: string;
+    has: boolean;
+}
+interface LuckPermsPrimaryGroupResult {
+    uuid: string;
+    primaryGroup: string;
+}
+interface LuckPermsCreateGroupResult {
+    name: string;
+    status: string;
+}
+/** Result of a promote/demote call along a track. */
+interface LuckPermsTrackActionResult {
+    uuid: string;
+    track: string;
+    /** `false` for statuses like `END_OF_TRACK`/`AMBIGUOUS_CALL`, where nothing was changed. */
+    success: boolean;
+    /** Raw LuckPerms `PromotionResult`/`DemotionResult` status, e.g. `"SUCCESS"`, `"END_OF_TRACK"`. */
+    status: string;
+    from: string | null;
+    to: string | null;
 }
 interface Advancement {
     key: string;
@@ -612,55 +676,151 @@ declare class PlaceholdersModule {
     replace(uuid: string, message: string): Promise<string>;
 }
 
+/** Extra fields accepted by the node-adding endpoints, on top of the context options. */
+interface AddPermissionOptions extends LuckPermsContextOptions {
+    /**
+     * Node value. Defaults to `true` server-side when omitted — pass `false`
+     * to add a negating node rather than a positive grant.
+     */
+    value?: boolean;
+    /**
+     * When the node should expire. Parsed server-side by
+     * `ValidationUtils.parseExpiry` — pass an ISO-8601 instant string (e.g.
+     * `"2026-12-31T00:00:00Z"`) or an epoch-seconds string. Omit for a node
+     * that never expires.
+     */
+    expiry?: string;
+}
+type SetGroupOptions = LuckPermsContextOptions & Pick<AddPermissionOptions, "expiry">;
+interface SetMetaValueOptions extends LuckPermsContextOptions {
+    /**
+     * Sort priority — higher wins when multiple prefix/suffix nodes are
+     * active at once. Defaults to `100` server-side when omitted, matching
+     * LuckPerms' own `/lp meta setprefix|setsuffix` default.
+     */
+    priority?: number;
+}
 /**
  * Wraps the `/v1/luckperms/*` routes. These only exist on the server when
- * the LuckPerms mod is loaded — calling any method here against a server
- * without it will fail (typically a 404). There's no separate "is this
- * available" flag from the SDK's side; check `client.plugins.list()` for
- * LuckPerms if you need to branch on it ahead of time.
+ * the LuckPerms plugin is loaded — calling any method here against a
+ * server without it throws `NoxAeApiServerError` with a 503 status.
+ * There's no separate "is this available" flag from the SDK's side;
+ * check `client.plugins.list()` for LuckPerms if you need to branch on
+ * it ahead of time.
  *
- * Unlike most other modules, these POST/DELETE bodies are sent as real
- * JSON (the server reads them with `ctx.bodyAsClass(...)`, not
+ * Unlike most other modules, every request body here is sent as real
+ * JSON (the server reads it with `ctx.bodyAsClass(...)`, not
  * `ctx.formParam(...)`) — do not add `form: true` to these calls.
+ *
+ * "Context" throughout this module means LuckPerms' `server`/`world`
+ * context keys, not the Bukkit/network server this SDK talks to — pass
+ * them when a node should only apply on a specific sub-server or world,
+ * and omit them for a global node.
  */
 declare class LuckPermsModule {
     private readonly http;
     constructor(http: HttpEngine);
-    /** Get the groups a player belongs to. */
+    /** Get the names of every group a player belongs to (via inheritance nodes). */
     getPlayerGroups(uuid: string): Promise<string[]>;
-    /** Get a player's effective permission nodes. */
+    /** Get every node (permissions, inheritance, prefix/suffix, meta, ...) held directly by a player. */
     getPlayerPermissions(uuid: string): Promise<PermissionNode[]>;
-    /** Add a permission node to a player. */
-    addPlayerPermission(uuid: string, permission: string, value?: boolean): Promise<void>;
-    /** Check whether a player has a given permission. */
-    checkPlayerPermission(uuid: string, permission: string): Promise<{
-        permission: string;
-        value: boolean;
-    }>;
-    /** Remove a permission node from a player. */
+    /** Add a permission node to a player. Defaults to a permanent, global, `true`-valued node. */
+    addPlayerPermission(uuid: string, permission: string, options?: AddPermissionOptions): Promise<void>;
+    /**
+     * Remove a permission node from a player by key. Note this matches on
+     * the permission string only — it does not target a specific
+     * value/expiry/context combination.
+     */
     removePlayerPermission(uuid: string, permission: string): Promise<void>;
-    /** Set a player's primary group. */
-    setPlayerGroup(uuid: string, group: string): Promise<void>;
-    /** Remove a group from a player. */
+    /**
+     * Check whether a player has a given permission, using LuckPerms'
+     * native resolution (inheritance, wildcards, contexts all apply).
+     */
+    checkPlayerPermission(uuid: string, permission: string): Promise<LuckPermsCheckPermissionResult>;
+    /** Get a player's primary group name. */
+    getPlayerPrimaryGroup(uuid: string): Promise<LuckPermsPrimaryGroupResult>;
+    /**
+     * Set a player's primary group. This both adds the corresponding
+     * inheritance node (so permissions actually resolve from the group) and
+     * updates the primary-group label — mirrors `/lp user <target> parent
+     * add <group>` plus `/lp user <target> setprimarygroup <group>`.
+     */
+    setPlayerGroup(uuid: string, group: string, options?: SetGroupOptions): Promise<void>;
+    /**
+     * Remove a group's inheritance node from a player. Does **not** change
+     * their primary group — call `setPlayerGroup()` with the new group
+     * afterward if you're reassigning rank rather than just removing one
+     * of several parents.
+     */
     removePlayerGroup(uuid: string, groupName: string): Promise<void>;
-    /** List all known groups. */
+    /**
+     * Promote a player one step up a track. If the result isn't successful
+     * (e.g. `END_OF_TRACK`, `AMBIGUOUS_CALL`), the player's data is left
+     * untouched — check `.success`/`.status` on the result rather than
+     * assuming the call always moves them.
+     */
+    promotePlayer(uuid: string, track: string, options?: LuckPermsContextOptions): Promise<LuckPermsTrackActionResult>;
+    /** Demote a player one step down a track. See `promotePlayer()` for the result semantics. */
+    demotePlayer(uuid: string, track: string, options?: LuckPermsContextOptions): Promise<LuckPermsTrackActionResult>;
+    /** Get a player's resolved prefix, suffix, and custom meta key-values. */
+    getPlayerMeta(uuid: string): Promise<MetaInfo>;
+    /**
+     * Set a player's prefix. Behaves like a "set", not an "add" — any
+     * existing prefix node (in any context) is cleared first, so a player
+     * only ever has one active prefix from this call.
+     */
+    setPlayerPrefix(uuid: string, prefix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a player's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setPlayerSuffix(uuid: string, suffix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a custom meta key-value pair on a player, replacing any existing value(s) for that key. */
+    setPlayerMeta(uuid: string, key: string, value: string, options?: LuckPermsContextOptions): Promise<void>;
+    /** Remove a custom meta key from a player (all values/contexts for that key). */
+    removePlayerMeta(uuid: string, key: string): Promise<void>;
+    /** List the names of every group registered in LuckPerms. */
     getGroups(): Promise<string[]>;
     /**
      * Create a new LuckPerms group. The name is lowercased server-side.
      * Throws `NoxAeApiError` with a 409 status if the group already exists.
      */
-    createGroup(name: string): Promise<{
-        name: string;
-        status: string;
-    }>;
+    createGroup(name: string): Promise<LuckPermsCreateGroupResult>;
     /**
      * Delete a LuckPerms group by name.
      * The `default` group can't be deleted (400 — every user without an
      * explicit group inherits from it) and a 404 is thrown if it doesn't exist.
      */
     deleteGroup(name: string): Promise<void>;
-    /** Get the permissions attached to a specific group. */
-    getGroupPermissions(name: string): Promise<GroupInfo>;
+    /** Get every node held directly by a group. */
+    getGroupPermissions(name: string): Promise<PermissionNode[]>;
+    /** Add a permission node to a group. Same options/defaults as `addPlayerPermission()`. */
+    addGroupPermission(name: string, permission: string, options?: AddPermissionOptions): Promise<void>;
+    /** Remove a permission node from a group by key (matches on permission string only). */
+    removeGroupPermission(name: string, permission: string): Promise<void>;
+    /** Get full info for a group: name, display name, weight, and all its nodes. */
+    getGroupInfo(name: string): Promise<GroupInfo>;
+    /**
+     * Update a group's weight and/or display name. Provide at least one of
+     * the two fields — the server 400s otherwise. Passing an empty/blank
+     * `displayName` resets it to the default rather than setting a blank one.
+     * Returns the group's full updated info.
+     */
+    updateGroup(name: string, updates: {
+        weight?: number;
+        displayName?: string | null;
+    }): Promise<GroupInfo>;
+    /** Get a group's resolved prefix, suffix, and custom meta key-values. */
+    getGroupMeta(name: string): Promise<MetaInfo>;
+    /** Set a group's prefix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setGroupPrefix(name: string, prefix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a group's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setGroupSuffix(name: string, suffix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a custom meta key-value pair on a group, replacing any existing value(s) for that key. */
+    setGroupMeta(name: string, key: string, value: string, options?: LuckPermsContextOptions): Promise<void>;
+    /** Remove a custom meta key from a group (all values/contexts for that key). */
+    removeGroupMeta(name: string, key: string): Promise<void>;
+    /** List the names of every track registered in LuckPerms. */
+    getTracks(): Promise<string[]>;
+    /** Get a track's name and its ordered list of groups (lowest to highest rank). */
+    getTrack(name: string): Promise<TrackInfo>;
 }
 
 /**
@@ -681,6 +841,27 @@ declare class NoxAuthModule {
     checkPassword(name: string, password: string): Promise<PasswordCheckResult>;
 }
 
+/**
+ * Wraps the /v1/identity/* routes.
+ *
+ * Resolves a username to its deterministic network-wide identityUuid and
+ * returns whether the player has ever joined this backend server (along with
+ * this server's localUuid).
+ */
+declare class IdentityModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /**
+     * Resolves a player's network-wide identity and local UUID status.
+     *
+     * Unlike players.resolve(name), this does NOT throw 404 if the player
+     * has never joined this server. Instead, identityUuid is always computed
+     * deterministically from the username, and hasPlayedBefore will be false
+     * with localUuid: null.
+     */
+    get(name: string): Promise<IdentityInfo>;
+}
+
 /**
  * Wraps the `/v1/skills/*` routes (mcMMO / AuraSkills).
  */
@@ -918,6 +1099,7 @@ declare class NoxAeApiSocket {
 
 declare class NoxAeApiClient {
     readonly players: PlayersModule;
+    readonly identity: IdentityModule;
     readonly economy: EconomyModule;
     readonly server: ServerModule;
     readonly worlds: WorldsModule;
@@ -1041,4 +1223,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 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 };
+export { type AddPermissionOptions, type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type IdentityInfo, IdentityModule, type IdentityServerInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type LuckPermsCheckPermissionResult, type LuckPermsContextOptions, type LuckPermsCreateGroupResult, type LuckPermsPrimaryGroupResult, type LuckPermsTrackActionResult, type MetaInfo, 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 SetGroupOptions, type SetMetaValueOptions, type SkillInfo, type TopBalanceEntry, type TrackInfo, type WhitelistEntry, type World };

package/dist/index.d.ts

@@ -82,6 +82,19 @@ interface PlayerResolveResult {
     name: string;
     uuid: string;
 }
+interface IdentityServerInfo {
+    id: string;
+    label: string;
+}
+/** Result of resolving player identity via `GET /v1/identity/{name}`. */
+interface IdentityInfo {
+    username: string;
+    identityUuid: string;
+    localUuid: string | null;
+    server: IdentityServerInfo;
+    onlineMode: boolean;
+    hasPlayedBefore: boolean;
+}
 interface ServerHealth {
     cpus: number;
     uptime: number;
@@ -168,16 +181,67 @@ interface TopBalanceEntry {
     uuid: string;
     balance: number;
 }
-interface GroupInfo {
-    name: string;
-    permissions: string[];
-}
+/** A single LuckPerms node (permission, inheritance, prefix, etc.) as returned by the server. */
 interface PermissionNode {
     permission: string;
     value: boolean;
+    /** Epoch seconds, or `0` for a permanent (non-expiring) node. */
     expiry: number;
-    server: string | null;
-    world: string | null;
+    /** Server context this node applies to, or the literal `"global"` if none was set. */
+    server: string;
+    /** World context this node applies to, or the literal `"global"` if none was set. */
+    world: string;
+}
+interface GroupInfo {
+    name: string;
+    /** `null` if the group has no display name node set. */
+    displayName: string | null;
+    weight: number;
+    permissions: PermissionNode[];
+}
+/** A player's or group's resolved prefix, suffix, and custom meta key-values. */
+interface MetaInfo {
+    prefix: string | null;
+    suffix: string | null;
+    /** LuckPerms keeps every value ever set per key; the highest-priority one wins in-game. */
+    meta: Record<string, string[]>;
+}
+/** A LuckPerms track (an ordered rank ladder used for promote/demote). */
+interface TrackInfo {
+    name: string;
+    /** Ordered from lowest to highest rank. */
+    groups: string[];
+}
+/** Optional server/world context that scopes a node to a subset of the network. */
+interface LuckPermsContextOptions {
+    /** e.g. `"survival"` — matches LuckPerms' `server` context key. */
+    server?: string;
+    /** e.g. `"world_nether"` — matches LuckPerms' `world` context key. */
+    world?: string;
+}
+interface LuckPermsCheckPermissionResult {
+    uuid: string;
+    permission: string;
+    has: boolean;
+}
+interface LuckPermsPrimaryGroupResult {
+    uuid: string;
+    primaryGroup: string;
+}
+interface LuckPermsCreateGroupResult {
+    name: string;
+    status: string;
+}
+/** Result of a promote/demote call along a track. */
+interface LuckPermsTrackActionResult {
+    uuid: string;
+    track: string;
+    /** `false` for statuses like `END_OF_TRACK`/`AMBIGUOUS_CALL`, where nothing was changed. */
+    success: boolean;
+    /** Raw LuckPerms `PromotionResult`/`DemotionResult` status, e.g. `"SUCCESS"`, `"END_OF_TRACK"`. */
+    status: string;
+    from: string | null;
+    to: string | null;
 }
 interface Advancement {
     key: string;
@@ -612,55 +676,151 @@ declare class PlaceholdersModule {
     replace(uuid: string, message: string): Promise<string>;
 }
 
+/** Extra fields accepted by the node-adding endpoints, on top of the context options. */
+interface AddPermissionOptions extends LuckPermsContextOptions {
+    /**
+     * Node value. Defaults to `true` server-side when omitted — pass `false`
+     * to add a negating node rather than a positive grant.
+     */
+    value?: boolean;
+    /**
+     * When the node should expire. Parsed server-side by
+     * `ValidationUtils.parseExpiry` — pass an ISO-8601 instant string (e.g.
+     * `"2026-12-31T00:00:00Z"`) or an epoch-seconds string. Omit for a node
+     * that never expires.
+     */
+    expiry?: string;
+}
+type SetGroupOptions = LuckPermsContextOptions & Pick<AddPermissionOptions, "expiry">;
+interface SetMetaValueOptions extends LuckPermsContextOptions {
+    /**
+     * Sort priority — higher wins when multiple prefix/suffix nodes are
+     * active at once. Defaults to `100` server-side when omitted, matching
+     * LuckPerms' own `/lp meta setprefix|setsuffix` default.
+     */
+    priority?: number;
+}
 /**
  * Wraps the `/v1/luckperms/*` routes. These only exist on the server when
- * the LuckPerms mod is loaded — calling any method here against a server
- * without it will fail (typically a 404). There's no separate "is this
- * available" flag from the SDK's side; check `client.plugins.list()` for
- * LuckPerms if you need to branch on it ahead of time.
+ * the LuckPerms plugin is loaded — calling any method here against a
+ * server without it throws `NoxAeApiServerError` with a 503 status.
+ * There's no separate "is this available" flag from the SDK's side;
+ * check `client.plugins.list()` for LuckPerms if you need to branch on
+ * it ahead of time.
  *
- * Unlike most other modules, these POST/DELETE bodies are sent as real
- * JSON (the server reads them with `ctx.bodyAsClass(...)`, not
+ * Unlike most other modules, every request body here is sent as real
+ * JSON (the server reads it with `ctx.bodyAsClass(...)`, not
  * `ctx.formParam(...)`) — do not add `form: true` to these calls.
+ *
+ * "Context" throughout this module means LuckPerms' `server`/`world`
+ * context keys, not the Bukkit/network server this SDK talks to — pass
+ * them when a node should only apply on a specific sub-server or world,
+ * and omit them for a global node.
  */
 declare class LuckPermsModule {
     private readonly http;
     constructor(http: HttpEngine);
-    /** Get the groups a player belongs to. */
+    /** Get the names of every group a player belongs to (via inheritance nodes). */
     getPlayerGroups(uuid: string): Promise<string[]>;
-    /** Get a player's effective permission nodes. */
+    /** Get every node (permissions, inheritance, prefix/suffix, meta, ...) held directly by a player. */
     getPlayerPermissions(uuid: string): Promise<PermissionNode[]>;
-    /** Add a permission node to a player. */
-    addPlayerPermission(uuid: string, permission: string, value?: boolean): Promise<void>;
-    /** Check whether a player has a given permission. */
-    checkPlayerPermission(uuid: string, permission: string): Promise<{
-        permission: string;
-        value: boolean;
-    }>;
-    /** Remove a permission node from a player. */
+    /** Add a permission node to a player. Defaults to a permanent, global, `true`-valued node. */
+    addPlayerPermission(uuid: string, permission: string, options?: AddPermissionOptions): Promise<void>;
+    /**
+     * Remove a permission node from a player by key. Note this matches on
+     * the permission string only — it does not target a specific
+     * value/expiry/context combination.
+     */
     removePlayerPermission(uuid: string, permission: string): Promise<void>;
-    /** Set a player's primary group. */
-    setPlayerGroup(uuid: string, group: string): Promise<void>;
-    /** Remove a group from a player. */
+    /**
+     * Check whether a player has a given permission, using LuckPerms'
+     * native resolution (inheritance, wildcards, contexts all apply).
+     */
+    checkPlayerPermission(uuid: string, permission: string): Promise<LuckPermsCheckPermissionResult>;
+    /** Get a player's primary group name. */
+    getPlayerPrimaryGroup(uuid: string): Promise<LuckPermsPrimaryGroupResult>;
+    /**
+     * Set a player's primary group. This both adds the corresponding
+     * inheritance node (so permissions actually resolve from the group) and
+     * updates the primary-group label — mirrors `/lp user <target> parent
+     * add <group>` plus `/lp user <target> setprimarygroup <group>`.
+     */
+    setPlayerGroup(uuid: string, group: string, options?: SetGroupOptions): Promise<void>;
+    /**
+     * Remove a group's inheritance node from a player. Does **not** change
+     * their primary group — call `setPlayerGroup()` with the new group
+     * afterward if you're reassigning rank rather than just removing one
+     * of several parents.
+     */
     removePlayerGroup(uuid: string, groupName: string): Promise<void>;
-    /** List all known groups. */
+    /**
+     * Promote a player one step up a track. If the result isn't successful
+     * (e.g. `END_OF_TRACK`, `AMBIGUOUS_CALL`), the player's data is left
+     * untouched — check `.success`/`.status` on the result rather than
+     * assuming the call always moves them.
+     */
+    promotePlayer(uuid: string, track: string, options?: LuckPermsContextOptions): Promise<LuckPermsTrackActionResult>;
+    /** Demote a player one step down a track. See `promotePlayer()` for the result semantics. */
+    demotePlayer(uuid: string, track: string, options?: LuckPermsContextOptions): Promise<LuckPermsTrackActionResult>;
+    /** Get a player's resolved prefix, suffix, and custom meta key-values. */
+    getPlayerMeta(uuid: string): Promise<MetaInfo>;
+    /**
+     * Set a player's prefix. Behaves like a "set", not an "add" — any
+     * existing prefix node (in any context) is cleared first, so a player
+     * only ever has one active prefix from this call.
+     */
+    setPlayerPrefix(uuid: string, prefix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a player's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setPlayerSuffix(uuid: string, suffix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a custom meta key-value pair on a player, replacing any existing value(s) for that key. */
+    setPlayerMeta(uuid: string, key: string, value: string, options?: LuckPermsContextOptions): Promise<void>;
+    /** Remove a custom meta key from a player (all values/contexts for that key). */
+    removePlayerMeta(uuid: string, key: string): Promise<void>;
+    /** List the names of every group registered in LuckPerms. */
     getGroups(): Promise<string[]>;
     /**
      * Create a new LuckPerms group. The name is lowercased server-side.
      * Throws `NoxAeApiError` with a 409 status if the group already exists.
      */
-    createGroup(name: string): Promise<{
-        name: string;
-        status: string;
-    }>;
+    createGroup(name: string): Promise<LuckPermsCreateGroupResult>;
     /**
      * Delete a LuckPerms group by name.
      * The `default` group can't be deleted (400 — every user without an
      * explicit group inherits from it) and a 404 is thrown if it doesn't exist.
      */
     deleteGroup(name: string): Promise<void>;
-    /** Get the permissions attached to a specific group. */
-    getGroupPermissions(name: string): Promise<GroupInfo>;
+    /** Get every node held directly by a group. */
+    getGroupPermissions(name: string): Promise<PermissionNode[]>;
+    /** Add a permission node to a group. Same options/defaults as `addPlayerPermission()`. */
+    addGroupPermission(name: string, permission: string, options?: AddPermissionOptions): Promise<void>;
+    /** Remove a permission node from a group by key (matches on permission string only). */
+    removeGroupPermission(name: string, permission: string): Promise<void>;
+    /** Get full info for a group: name, display name, weight, and all its nodes. */
+    getGroupInfo(name: string): Promise<GroupInfo>;
+    /**
+     * Update a group's weight and/or display name. Provide at least one of
+     * the two fields — the server 400s otherwise. Passing an empty/blank
+     * `displayName` resets it to the default rather than setting a blank one.
+     * Returns the group's full updated info.
+     */
+    updateGroup(name: string, updates: {
+        weight?: number;
+        displayName?: string | null;
+    }): Promise<GroupInfo>;
+    /** Get a group's resolved prefix, suffix, and custom meta key-values. */
+    getGroupMeta(name: string): Promise<MetaInfo>;
+    /** Set a group's prefix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setGroupPrefix(name: string, prefix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a group's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+    setGroupSuffix(name: string, suffix: string, options?: SetMetaValueOptions): Promise<void>;
+    /** Set a custom meta key-value pair on a group, replacing any existing value(s) for that key. */
+    setGroupMeta(name: string, key: string, value: string, options?: LuckPermsContextOptions): Promise<void>;
+    /** Remove a custom meta key from a group (all values/contexts for that key). */
+    removeGroupMeta(name: string, key: string): Promise<void>;
+    /** List the names of every track registered in LuckPerms. */
+    getTracks(): Promise<string[]>;
+    /** Get a track's name and its ordered list of groups (lowest to highest rank). */
+    getTrack(name: string): Promise<TrackInfo>;
 }
 
 /**
@@ -681,6 +841,27 @@ declare class NoxAuthModule {
     checkPassword(name: string, password: string): Promise<PasswordCheckResult>;
 }
 
+/**
+ * Wraps the /v1/identity/* routes.
+ *
+ * Resolves a username to its deterministic network-wide identityUuid and
+ * returns whether the player has ever joined this backend server (along with
+ * this server's localUuid).
+ */
+declare class IdentityModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /**
+     * Resolves a player's network-wide identity and local UUID status.
+     *
+     * Unlike players.resolve(name), this does NOT throw 404 if the player
+     * has never joined this server. Instead, identityUuid is always computed
+     * deterministically from the username, and hasPlayedBefore will be false
+     * with localUuid: null.
+     */
+    get(name: string): Promise<IdentityInfo>;
+}
+
 /**
  * Wraps the `/v1/skills/*` routes (mcMMO / AuraSkills).
  */
@@ -918,6 +1099,7 @@ declare class NoxAeApiSocket {
 
 declare class NoxAeApiClient {
     readonly players: PlayersModule;
+    readonly identity: IdentityModule;
     readonly economy: EconomyModule;
     readonly server: ServerModule;
     readonly worlds: WorldsModule;
@@ -1041,4 +1223,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 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 };
+export { type AddPermissionOptions, type Advancement, type CurrencyBalance, type CurrencyTopEntry, type EconomyInfo, type GroupInfo, type IdentityInfo, IdentityModule, type IdentityServerInfo, type InventoryItem, type LeaderboardEntry, type LeaderboardSourceInfo, type LuckPermsCheckPermissionResult, type LuckPermsContextOptions, type LuckPermsCreateGroupResult, type LuckPermsPrimaryGroupResult, type LuckPermsTrackActionResult, type MetaInfo, 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 SetGroupOptions, type SetMetaValueOptions, type SkillInfo, type TopBalanceEntry, type TrackInfo, type WhitelistEntry, type World };