erlc-api 3.3.1 → 3.3.2-a

package/src/functions/server/getPlayers.js

@@ -1,47 +1,14 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { requestServer } = require("./requestServer.js");
 
 /**
- * Retrieves current players from a server
+ * Retrieves current players from a server.
  * @param {string} serverToken - The server API key
  * @returns {Promise<Array>} Promise that resolves to array of current players
  */
-module.exports = (serverToken) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const headers = {
-        "Server-Key": serverToken,
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/players`, {
-        headers: headers,
-        timeout: 10000, // 10 second timeout
-      });
-
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
-
-      const data = await res.json();
-      resolve(Array.isArray(data) ? data : []);
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = (serverToken) =>
+  requestServer(serverToken, {
+    endpoint: "players",
+    includes: ["Players"],
+    defaultValue: [],
+    transform: (data) => (Array.isArray(data?.Players) ? data.Players : []),
   });
-};

package/src/functions/server/getQueue.js

@@ -1,47 +1,14 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { requestServer } = require("./requestServer.js");
 
 /**
- * Retrieves server queue information
+ * Retrieves server queue information.
  * @param {string} serverToken - The server API key
  * @returns {Promise<Array>} Promise that resolves to array of queued player IDs
  */
-module.exports = (serverToken) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const headers = {
-        "Server-Key": serverToken,
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/queue`, {
-        headers: headers,
-        timeout: 10000, // 10 second timeout
-      });
-
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
-
-      const data = await res.json();
-      resolve(Array.isArray(data) ? data : []);
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = (serverToken) =>
+  requestServer(serverToken, {
+    endpoint: "queue",
+    includes: ["Queue"],
+    defaultValue: [],
+    transform: (data) => (Array.isArray(data?.Queue) ? data.Queue : []),
   });
-};

package/src/functions/server/getServer.js

@@ -1,100 +1,82 @@
-const { BASEURL, Vanity } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { Vanity } = require("../../constants.js");
+const { requestServer } = require("./requestServer.js");
 
-module.exports = (serverToken) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
+async function getUsername(fetch, userId) {
+  try {
+    const response = await fetch(`https://users.roblox.com/v1/users/${userId}`);
+    const userData = await response.json();
+
+    if (!response.ok) {
+      console.warn(`Warning: Could not fetch username for ID: ${userId}`);
+      return `User:${userId}`;
     }
 
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
+    return userData.name;
+  } catch (error) {
+    console.warn(`Warning: Error fetching username for ID: ${userId}`, error);
+    return `User:${userId}`;
+  }
+}
 
-      const headers = {
-        "Server-Key": serverToken,
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
+function normalizeIncludes(options = {}) {
+  const includeMap = {
+    players: "Players",
+    staff: "Staff",
+    joinLogs: "JoinLogs",
+    queue: "Queue",
+    killLogs: "KillLogs",
+    commandLogs: "CommandLogs",
+    modCalls: "ModCalls",
+    emergencyCalls: "EmergencyCalls",
+    vehicles: "Vehicles",
+  };
 
-      const res = await fetch.default(`${BASEURL}/server`, {
-        headers: headers,
-        timeout: 10000, // 10 second timeout
-      });
+  return Object.entries(includeMap)
+    .filter(([option]) => options[option])
+    .map(([, include]) => include);
+}
 
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
+module.exports = (serverToken, options = {}) => {
+  const includes = normalizeIncludes(options);
 
-      const data = await res.json();
-
-      const getUsername = async (userId) => {
-        try {
-          const response = await fetch.default(
-            `https://users.roblox.com/v1/users/${userId}`
-          );
-          const userData = await response.json();
-          if (!response.ok) {
-            console.warn(`Warning: Could not fetch username for ID: ${userId}`);
-            return `User:${userId}`; // Fallback format
-          }
-          return userData.name;
-        } catch (error) {
-          console.warn(
-            `Warning: Error fetching username for ID: ${userId}`,
-            error
-          );
-          return `User:${userId}`; // Fallback format
-        }
-      };
+  return requestServer(serverToken, {
+    endpoint: "server",
+    includes,
+    transform: async (data) => {
+      const fetch =
+        typeof globalThis.fetch === "function"
+          ? globalThis.fetch
+          : (await import("node-fetch")).default;
 
       try {
-        // Get owner username
-        const ownerUsername = await getUsername(data.OwnerId);
-
-        // Get co-owner usernames (handle empty array case)
+        const ownerUsername = await getUsername(fetch, data.OwnerId);
         const coOwnerUsernames =
           data.CoOwnerIds && data.CoOwnerIds.length > 0
-            ? await Promise.all(data.CoOwnerIds.map(getUsername))
+            ? await Promise.all(data.CoOwnerIds.map((id) => getUsername(fetch, id)))
             : [];
 
-        // Create vanity URL
-        const vanityURL = `${Vanity}${data.JoinKey}`;
-
-        // Add the new properties to the response
         const enhancedData = {
           ...data,
           OwnerUsername: ownerUsername,
           CoOwnerUsernames: coOwnerUsernames,
-          VanityURL: vanityURL,
+          VanityURL: `${Vanity}${data.JoinKey}`,
         };
 
-        // Remove the original ID properties as they're now converted to usernames
         delete enhancedData.OwnerId;
         delete enhancedData.CoOwnerIds;
 
-        resolve(enhancedData);
+        return enhancedData;
       } catch (error) {
-        // If username fetching fails, still return the original data with IDs
         console.warn(
           "Warning: Could not fetch usernames, returning data with IDs:",
-          error
+          error,
         );
-        const fallbackData = {
+
+        return {
           ...data,
           VanityURL: `${Vanity}${data.JoinKey}`,
         };
-        resolve(fallbackData);
       }
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+    },
   });
 };

package/src/functions/server/getStaff.js

@@ -1,47 +1,14 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { requestServer } = require("./requestServer.js");
 
 /**
- * Retrieves server staff information
+ * Retrieves server staff information.
  * @param {string} serverToken - The server API key
  * @returns {Promise<Object>} Promise that resolves to server staff object
  */
-module.exports = (serverToken) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const headers = {
-        "Server-Key": serverToken,
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/staff`, {
-        headers: headers,
-        timeout: 10000, // 10 second timeout
-      });
-
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
-
-      const data = await res.json();
-      resolve(data || { CoOwners: [], Admins: {}, Mods: {} });
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = (serverToken) =>
+  requestServer(serverToken, {
+    endpoint: "staff",
+    includes: ["Staff"],
+    defaultValue: { Admins: {}, Mods: {}, Helpers: {} },
+    transform: (data) => data?.Staff || { Admins: {}, Mods: {}, Helpers: {} },
   });
-};

package/src/functions/server/getVehicles.js

@@ -1,47 +1,14 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { requestServer } = require("./requestServer.js");
 
 /**
- * Retrieves server vehicles information
+ * Retrieves server vehicles information.
  * @param {string} serverToken - The server API key
  * @returns {Promise<Array>} Promise that resolves to array of vehicles
  */
-module.exports = (serverToken) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const headers = {
-        "Server-Key": serverToken,
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/vehicles`, {
-        headers: headers,
-        timeout: 10000, // 10 second timeout
-      });
-
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
-
-      const data = await res.json();
-      resolve(Array.isArray(data) ? data : []);
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = (serverToken) =>
+  requestServer(serverToken, {
+    endpoint: "vehicles",
+    includes: ["Vehicles"],
+    defaultValue: [],
+    transform: (data) => (Array.isArray(data?.Vehicles) ? data.Vehicles : []),
   });
-};

package/src/functions/server/requestServer.js

@@ -0,0 +1,179 @@
+const { BASEURL, LEGACY_BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
+const cache = require("../../utils/cache.js");
+
+function assertServerToken(serverToken) {
+  if (!serverToken || typeof serverToken !== "string") {
+    throw new Error("Server token is required and must be a string");
+  }
+}
+
+function buildHeaders(serverToken, config, extraHeaders = {}) {
+  const headers = {
+    "Server-Key": serverToken,
+    ...extraHeaders,
+  };
+
+  if (config?.globalToken) {
+    headers["Authorization"] = config.globalToken;
+  }
+
+  return headers;
+}
+
+async function getFetch() {
+  const { config } = require("../../erlc.js");
+
+  if (config?.fetch) {
+    return {
+      fetch: config.fetch,
+      config,
+    };
+  }
+
+  if (typeof globalThis.fetch === "function") {
+    return {
+      fetch: globalThis.fetch,
+      config,
+    };
+  }
+
+  const fetch = await import("node-fetch");
+
+  return {
+    fetch: fetch.default,
+    config,
+  };
+}
+
+async function readError(res) {
+  return res.json().catch(() => ({ error: "Unknown API error" }));
+}
+
+function buildServerUrl(includes = []) {
+  const url = new URL(`${BASEURL}/server`);
+
+  for (const include of includes) {
+    url.searchParams.set(include, "true");
+  }
+
+  return url.toString();
+}
+
+async function requestJson(url, options) {
+  const res = await options.fetch(url, options.init);
+
+  if (!res.ok) {
+    const errorData = await readError(res);
+    throw await processError(res, errorData);
+  }
+
+  return res.json();
+}
+
+async function requestServer(serverToken, options = {}) {
+  assertServerToken(serverToken);
+
+  const {
+    endpoint = "server",
+    includes = [],
+    defaultValue = {},
+    transform = (data) => data,
+  } = options;
+
+  const { fetch, config } = await getFetch();
+  const useCache = !!config?.cache?.enabled;
+  const cacheExtras = includes.length ? includes.join(",") : "";
+  const key = cache.makeKey(endpoint, serverToken, cacheExtras);
+
+  if (useCache) {
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  const data = await requestJson(buildServerUrl(includes), {
+    fetch,
+    init: {
+      headers: buildHeaders(serverToken, config),
+      timeout: 10000,
+    },
+  });
+
+  const value = (await transform(data)) ?? defaultValue;
+
+  if (useCache) {
+    const ttlMs = cache.getTTL(endpoint, config);
+    cache.set(key, value, ttlMs);
+  }
+
+  return value;
+}
+
+async function requestApi(serverToken, path, options = {}) {
+  assertServerToken(serverToken);
+
+  const {
+    baseUrl = BASEURL,
+    method = "GET",
+    endpoint = path,
+    body,
+    defaultValue = {},
+    transform = (data) => data,
+    timeout = 10000,
+    useCache = true,
+  } = options;
+
+  const { fetch, config } = await getFetch();
+  const shouldCache = method === "GET" && useCache && !!config?.cache?.enabled;
+  const key = cache.makeKey(endpoint, serverToken);
+
+  if (shouldCache) {
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  const headers = buildHeaders(
+    serverToken,
+    config,
+    body ? { "Content-Type": "application/json" } : {},
+  );
+
+  const data = await requestJson(`${baseUrl}${path}`, {
+    fetch,
+    init: {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      timeout,
+    },
+  });
+
+  const value = (await transform(data)) ?? defaultValue;
+
+  if (shouldCache) {
+    const ttlMs = cache.getTTL(endpoint, config);
+    cache.set(key, value, ttlMs);
+  }
+
+  return value;
+}
+
+async function requestLegacyServer(serverToken, path, options = {}) {
+  return requestApi(serverToken, path, {
+    ...options,
+    baseUrl: LEGACY_BASEURL,
+  });
+}
+
+module.exports = {
+  assertServerToken,
+  buildHeaders,
+  getFetch,
+  requestServer,
+  requestApi,
+  requestLegacyServer,
+};

package/src/functions/server/runCommand.js

@@ -1,61 +1,30 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { assertServerToken, requestApi } = require("./requestServer.js");
 
 /**
- * Executes a command on the server
+ * Executes a command on the server.
  * @param {string} serverToken - The server API key
  * @param {string} command - The command to execute
  * @returns {Promise<boolean>} Promise that resolves to true if command was executed successfully
  */
-module.exports = (serverToken, command) => {
-  return new Promise(async (resolve, reject) => {
-    // Input validation
-    if (!serverToken || typeof serverToken !== "string") {
-      return reject(new Error("Server token is required and must be a string"));
-    }
-
-    if (!command || typeof command !== "string") {
-      return reject(new Error("Command is required and must be a string"));
-    }
-
-    if (command.trim().length === 0) {
-      return reject(new Error("Command cannot be empty"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const requestBody = JSON.stringify({ command: command.trim() });
-
-      const headers = {
-        "Server-Key": serverToken,
-        "Content-Type": "application/json",
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/command`, {
-        method: "POST",
-        headers: headers,
-        body: requestBody,
-        timeout: 15000, // 15 second timeout for commands
-      });
-
-      if (!res.ok) {
-        const errorData = await res
-          .json()
-          .catch(() => ({ error: "Unknown API error" }));
-        const error = await processError(res, errorData);
-        return reject(error);
-      }
-
-      // Command executed successfully
-      resolve(true);
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = async (serverToken, command) => {
+  assertServerToken(serverToken);
+
+  if (!command || typeof command !== "string") {
+    throw new Error("Command is required and must be a string");
+  }
+
+  const trimmedCommand = command.trim();
+  if (trimmedCommand.length === 0) {
+    throw new Error("Command cannot be empty");
+  }
+
+  await requestApi(serverToken, "/server/command", {
+    method: "POST",
+    endpoint: "command",
+    body: { command: trimmedCommand },
+    timeout: 15000,
+    useCache: false,
   });
+
+  return true;
 };