@wumx-labs/noxaeapi-sdk 0.4.2 → 0.5.1

package/README.md

@@ -31,10 +31,21 @@ 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,
+// Cross-server network identity (deterministic identityUuid + local server status):
+const identity = await client.identity.get("NoxlyDev");
+
+// Resolve a name to a local 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);
+
+// LuckPerms (requires the plugin to be loaded on the target server):
+await client.luckperms.setPlayerGroup(uuid, "vip");
+await client.luckperms.addPlayerPermission(uuid, "essentials.fly", { expiry: "2026-12-31T00:00:00Z" });
+const { has } = await client.luckperms.checkPlayerPermission(uuid, "essentials.fly");
+await client.luckperms.promotePlayer(uuid, "default"); // moves them up the "default" track
+const group = await client.luckperms.getGroupInfo("vip");
+await client.luckperms.setGroupPrefix("vip", "&b[VIP] ");
 ```
 
 ### From environment variables

package/dist/index.cjs

@@ -652,26 +652,44 @@ var LuckPermsModule = class {
     this.http = http;
   }
   http;
-  /** Get the groups a player belongs to. */
+  // ---------------------------------------------------------------
+  // Player permissions & groups
+  // ---------------------------------------------------------------
+  /** Get the names of every group a player belongs to (via inheritance nodes). */
   getPlayerGroups(uuid) {
     return this.http.request("GET", `luckperms/player/${encodeURIComponent(uuid)}/groups`);
   }
-  /** Get a player's effective permission nodes. */
+  /** Get every node (permissions, inheritance, prefix/suffix, meta, ...) held directly by a player. */
   getPlayerPermissions(uuid) {
     return this.http.request(
       "GET",
       `luckperms/player/${encodeURIComponent(uuid)}/permissions`
     );
   }
-  /** Add a permission node to a player. */
-  addPlayerPermission(uuid, permission, value = true) {
+  /** Add a permission node to a player. Defaults to a permanent, global, `true`-valued node. */
+  addPlayerPermission(uuid, permission, options = {}) {
     return this.http.request(
       "POST",
       `luckperms/player/${encodeURIComponent(uuid)}/permission`,
-      { body: { permission, value } }
+      { body: { permission, ...options } }
     );
   }
-  /** Check whether a player has a given permission. */
+  /**
+   * 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, permission) {
+    return this.http.request(
+      "DELETE",
+      `luckperms/player/${encodeURIComponent(uuid)}/permission`,
+      { body: { permission } }
+    );
+  }
+  /**
+   * Check whether a player has a given permission, using LuckPerms'
+   * native resolution (inheritance, wildcards, contexts all apply).
+   */
   checkPlayerPermission(uuid, permission) {
     return this.http.request(
       "POST",
@@ -679,30 +697,105 @@ var LuckPermsModule = class {
       { body: { permission } }
     );
   }
-  /** Remove a permission node from a player. */
-  removePlayerPermission(uuid, permission) {
+  /** Get a player's primary group name. */
+  getPlayerPrimaryGroup(uuid) {
     return this.http.request(
-      "DELETE",
-      `luckperms/player/${encodeURIComponent(uuid)}/permission`,
-      { body: { permission } }
+      "GET",
+      `luckperms/player/${encodeURIComponent(uuid)}/primary-group`
     );
   }
-  /** Set a player's primary group. */
-  setPlayerGroup(uuid, group) {
+  /**
+   * 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, group, options = {}) {
     return this.http.request(
       "POST",
       `luckperms/player/${encodeURIComponent(uuid)}/group`,
-      { body: { group } }
+      { body: { group, ...options } }
     );
   }
-  /** Remove a group from a player. */
+  /**
+   * 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, groupName) {
     return this.http.request(
       "DELETE",
       `luckperms/player/${encodeURIComponent(uuid)}/group/${encodeURIComponent(groupName)}`
     );
   }
-  /** 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, track, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/player/${encodeURIComponent(uuid)}/promote`,
+      { body: { track, ...options } }
+    );
+  }
+  /** Demote a player one step down a track. See `promotePlayer()` for the result semantics. */
+  demotePlayer(uuid, track, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/player/${encodeURIComponent(uuid)}/demote`,
+      { body: { track, ...options } }
+    );
+  }
+  // ---------------------------------------------------------------
+  // Player meta (prefix / suffix / custom meta)
+  // ---------------------------------------------------------------
+  /** Get a player's resolved prefix, suffix, and custom meta key-values. */
+  getPlayerMeta(uuid) {
+    return this.http.request("GET", `luckperms/player/${encodeURIComponent(uuid)}/meta`);
+  }
+  /**
+   * 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, prefix, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/player/${encodeURIComponent(uuid)}/meta/prefix`,
+      { body: { prefix, ...options } }
+    );
+  }
+  /** Set a player's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+  setPlayerSuffix(uuid, suffix, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/player/${encodeURIComponent(uuid)}/meta/suffix`,
+      { body: { suffix, ...options } }
+    );
+  }
+  /** Set a custom meta key-value pair on a player, replacing any existing value(s) for that key. */
+  setPlayerMeta(uuid, key, value, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/player/${encodeURIComponent(uuid)}/meta`,
+      { body: { key, value, ...options } }
+    );
+  }
+  /** Remove a custom meta key from a player (all values/contexts for that key). */
+  removePlayerMeta(uuid, key) {
+    return this.http.request(
+      "DELETE",
+      `luckperms/player/${encodeURIComponent(uuid)}/meta/${encodeURIComponent(key)}`
+    );
+  }
+  // ---------------------------------------------------------------
+  // Groups
+  // ---------------------------------------------------------------
+  /** List the names of every group registered in LuckPerms. */
   getGroups() {
     return this.http.request("GET", "luckperms/groups");
   }
@@ -721,10 +814,90 @@ var LuckPermsModule = class {
   deleteGroup(name) {
     return this.http.request("DELETE", `luckperms/group/${encodeURIComponent(name)}`);
   }
-  /** Get the permissions attached to a specific group. */
+  /** Get every node held directly by a group. */
   getGroupPermissions(name) {
     return this.http.request("GET", `luckperms/group/${encodeURIComponent(name)}/permissions`);
   }
+  /** Add a permission node to a group. Same options/defaults as `addPlayerPermission()`. */
+  addGroupPermission(name, permission, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/group/${encodeURIComponent(name)}/permission`,
+      { body: { permission, ...options } }
+    );
+  }
+  /** Remove a permission node from a group by key (matches on permission string only). */
+  removeGroupPermission(name, permission) {
+    return this.http.request(
+      "DELETE",
+      `luckperms/group/${encodeURIComponent(name)}/permission`,
+      { body: { permission } }
+    );
+  }
+  /** Get full info for a group: name, display name, weight, and all its nodes. */
+  getGroupInfo(name) {
+    return this.http.request("GET", `luckperms/group/${encodeURIComponent(name)}`);
+  }
+  /**
+   * 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, updates) {
+    return this.http.request("PUT", `luckperms/group/${encodeURIComponent(name)}`, {
+      body: updates
+    });
+  }
+  // ---------------------------------------------------------------
+  // Group meta (prefix / suffix / custom meta)
+  // ---------------------------------------------------------------
+  /** Get a group's resolved prefix, suffix, and custom meta key-values. */
+  getGroupMeta(name) {
+    return this.http.request("GET", `luckperms/group/${encodeURIComponent(name)}/meta`);
+  }
+  /** Set a group's prefix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+  setGroupPrefix(name, prefix, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/group/${encodeURIComponent(name)}/meta/prefix`,
+      { body: { prefix, ...options } }
+    );
+  }
+  /** Set a group's suffix. Same "set, not add" semantics as `setPlayerPrefix()`. */
+  setGroupSuffix(name, suffix, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/group/${encodeURIComponent(name)}/meta/suffix`,
+      { body: { suffix, ...options } }
+    );
+  }
+  /** Set a custom meta key-value pair on a group, replacing any existing value(s) for that key. */
+  setGroupMeta(name, key, value, options = {}) {
+    return this.http.request(
+      "POST",
+      `luckperms/group/${encodeURIComponent(name)}/meta`,
+      { body: { key, value, ...options } }
+    );
+  }
+  /** Remove a custom meta key from a group (all values/contexts for that key). */
+  removeGroupMeta(name, key) {
+    return this.http.request(
+      "DELETE",
+      `luckperms/group/${encodeURIComponent(name)}/meta/${encodeURIComponent(key)}`
+    );
+  }
+  // ---------------------------------------------------------------
+  // Tracks (rank ladders — promote/demote)
+  // ---------------------------------------------------------------
+  /** List the names of every track registered in LuckPerms. */
+  getTracks() {
+    return this.http.request("GET", "luckperms/tracks");
+  }
+  /** Get a track's name and its ordered list of groups (lowest to highest rank). */
+  getTrack(name) {
+    return this.http.request("GET", `luckperms/track/${encodeURIComponent(name)}`);
+  }
 };
 
 // src/modules/noxauth.ts
@@ -747,6 +920,25 @@ var NoxAuthModule = class {
   }
 };
 
+// src/modules/identity.ts
+var IdentityModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * 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) {
+    return this.http.request("GET", `identity/${encodeURIComponent(name)}`);
+  }
+};
+
 // src/modules/skills.ts
 var SkillsModule = class {
   constructor(http) {
@@ -1023,6 +1215,7 @@ function safeParse(text) {
 // src/client.ts
 var NoxAeApiClient = class _NoxAeApiClient {
   players;
+  identity;
   economy;
   server;
   worlds;
@@ -1057,6 +1250,7 @@ var NoxAeApiClient = class _NoxAeApiClient {
     this.baseUrl = options.baseUrl;
     this.apiKey = options.apiKey;
     this.players = new PlayersModule(this.http);
+    this.identity = new IdentityModule(this.http);
     this.economy = new EconomyModule(this.http);
     this.server = new ServerModule(this.http);
     this.worlds = new WorldsModule(this.http);
@@ -1126,6 +1320,7 @@ var NoxAeApiNetworkHubClient = class _NoxAeApiNetworkHubClient {
   }
 };
 
+exports.IdentityModule = IdentityModule;
 exports.NoxAeApiClient = NoxAeApiClient;
 exports.NoxAeApiError = NoxAeApiError;
 exports.NoxAeApiForbiddenError = NoxAeApiForbiddenError;