erlc-api 3.3.2-a → 3.3.3

package/README.md

@@ -30,53 +30,60 @@ bun add erlc-api
 
 ### Initialization
 
-You can use the library with or without a `Global Token` (required only for large-scale applications).
+You can initialize the client with your `Server Key` so every server request can reuse it automatically. A `Global Token` is optional and only required for large-scale applications.
 
 **JavaScript**
 ```javascript
 const erlc = require("erlc-api");
 
-// Simple initialization (Recommended for most users)
-const client = new erlc.Client();
+const client = new erlc.Client({
+  serverToken: "your-server-key-here",
+  // globalToken: "your-global-token-here", // Optional, for large apps
+});
+
+await client.ready;
 
-// Or with Global Token (For Large Apps)
-// const client = new erlc.Client({ globalToken: "..." });
+if (!client.connected) {
+  console.error("Could not connect:", client.connectionError.message);
+}
 ```
 
 **TypeScript**
 ```typescript
-import { Client, getServer } from "erlc-api";
+import { Client } from "erlc-api";
 
-const client = new Client();
+const client = new Client({
+  serverToken: "your-server-key-here",
+});
+
+await client.ready;
 ```
 
 ---
 
 ## 📖 Usage Examples
 
-Make sure to have your `Server Key` ready (get it from your private server settings in ER:LC).
+Make sure to have your `Server Key` ready (get it from your private server settings in ER:LC). When the key is configured in `Client`, you do not need to pass it again on every request.
 
 ### 🖥️ Server Information
 
 ```javascript
-const serverToken = "your-server-key-here";
-
 // Get server status
-const server = await erlc.getServer(serverToken);
+const server = await client.getServer();
 console.log(`Server: ${server.Name} | Players: ${server.CurrentPlayers}/${server.MaxPlayers}`);
 
 // Get connected players
-const players = await erlc.getPlayers(serverToken);
+const players = await client.getPlayers();
 console.table(players); // Shows name, ID, permission, and team
 
 // Get vehicles on the map
-const vehicles = await erlc.getVehicles(serverToken);
+const vehicles = await client.getVehicles();
 
 // Get emergency calls
-const emergencyCalls = await erlc.getEmergencyCalls(serverToken);
+const emergencyCalls = await client.getEmergencyCalls();
 
 // Fetch server info with v2 include flags in one request
-const fullServer = await erlc.getServer(serverToken, {
+const fullServer = await client.getServer({
   players: true,
   staff: true,
   emergencyCalls: true,
@@ -89,29 +96,29 @@ Access your server's activity history:
 
 ```javascript
 // Join/Leave Logs
-const joinLogs = await erlc.getJoinLogs(serverToken);
+const joinLogs = await client.getJoinLogs();
 
 // Kill Logs (Killfeed)
-const killLogs = await erlc.getKillLogs(serverToken);
+const killLogs = await client.getKillLogs();
 
 // Command Logs
-const commandLogs = await erlc.getCommandLogs(serverToken);
+const commandLogs = await client.getCommandLogs();
 
 // Mod Call Logs
-const modCalls = await erlc.getModcallLogs(serverToken);
+const modCalls = await client.getModcallLogs();
 ```
 
 ### 🛠️ Management & Administration
 
 ```javascript
 // Get Ban List
-const bans = await erlc.getBans(serverToken);
+const bans = await client.getBans();
 
 // Get Server Staff
-const staff = await erlc.getStaff(serverToken);
+const staff = await client.getStaff();
 
 // Get Queue
-const queue = await erlc.getQueue(serverToken);
+const queue = await client.getQueue();
 ```
 
 ### ⚡ Run Command
@@ -119,10 +126,19 @@ const queue = await erlc.getQueue(serverToken);
 Execute commands directly from your code:
 
 ```javascript
-const command = await erlc.runCommand(serverToken, ":announce This is an API test!");
+const command = await client.runCommand(":announce This is an API test!");
 console.log(command); // Returns true if successful
 ```
 
+### Manual Token Usage
+
+You can still pass the server token directly if you prefer the older style:
+
+```javascript
+const server = await erlc.getServer("your-server-key-here");
+const players = await erlc.getPlayers("your-server-key-here");
+```
+
 ---
 
 ## ⚠️ Error Handling
@@ -131,7 +147,8 @@ The library throws descriptive errors. You should wrap your calls in `try/catch`
 
 ```javascript
 try {
-  const data = await erlc.getServer("invalid-token");
+  const client = new erlc.Client({ serverToken: "invalid-token" });
+  await client.connect();
 } catch (error) {
   console.error(error.message); // e.g., "Forbidden: Access denied..."
 }

package/README_ES.md

@@ -30,57 +30,64 @@ bun add erlc-api
 
 ### Inicialización
 
-Puedes usar la librería con o sin un `Global Token` (requerido solo para aplicaciones a gran escala).
+Puedes iniciar el cliente con tu `Server Key` para reutilizarla automáticamente en todas las peticiones del servidor. El `Global Token` es opcional y solo se requiere para aplicaciones a gran escala.
 
 **JavaScript**
 
 ```javascript
 const erlc = require("erlc-api");
 
-// Inicialización simple (Recomendada para la mayoría)
-const client = new erlc.Client();
+const client = new erlc.Client({
+  serverToken: "tu-server-key-aqui",
+  // globalToken: "tu-global-token-aqui", // Opcional, para apps grandes
+});
+
+await client.ready;
 
-// O con Global Token (Para Large Apps)
-// const client = new erlc.Client({ globalToken: "..." });
+if (!client.connected) {
+  console.error("No se pudo conectar:", client.connectionError.message);
+}
 ```
 
 **TypeScript**
 
 ```typescript
-import { Client, getServer } from "erlc-api";
+import { Client } from "erlc-api";
 
-const client = new Client();
+const client = new Client({
+  serverToken: "tu-server-key-aqui",
+});
+
+await client.ready;
 ```
 
 ---
 
 ## 📖 Ejemplos de Uso
 
-Asegúrate de tener tu `Server Key` a mano (obtenla en los ajustes de tu servidor privado en ER:LC).
+Asegúrate de tener tu `Server Key` a mano (obtenla en los ajustes de tu servidor privado en ER:LC). Cuando la key está configurada en `Client`, no necesitas volver a pasarla en cada petición.
 
 ### 🖥️ Información del Servidor
 
 ```javascript
-const serverToken = "tu-server-key-aqui";
-
 // Obtener estado del servidor
-const server = await erlc.getServer(serverToken);
+const server = await client.getServer();
 console.log(
   `Servidor: ${server.Name} | Jugadores: ${server.CurrentPlayers}/${server.MaxPlayers}`,
 );
 
 // Obtener jugadores conectados
-const players = await erlc.getPlayers(serverToken);
+const players = await client.getPlayers();
 console.table(players); // Muestra nombre, ID, permisos y equipo
 
 // Obtener vehículos en el mapa
-const vehicles = await erlc.getVehicles(serverToken);
+const vehicles = await client.getVehicles();
 
 // Obtener llamadas de emergencia
-const emergencyCalls = await erlc.getEmergencyCalls(serverToken);
+const emergencyCalls = await client.getEmergencyCalls();
 
 // Obtener información del servidor con includes de v2 en una sola petición
-const fullServer = await erlc.getServer(serverToken, {
+const fullServer = await client.getServer({
   players: true,
   staff: true,
   emergencyCalls: true,
@@ -93,38 +100,50 @@ Accede a los historiales de actividad de tu servidor:
 
 ```javascript
 // Logs de Entradas/Salidas
-const joinLogs = await erlc.getJoinLogs(serverToken);
+const joinLogs = await client.getJoinLogs();
 
 // Logs de Muertes (Killfeed)
-const killLogs = await erlc.getKillLogs(serverToken);
+const killLogs = await client.getKillLogs();
 
 // Logs de Comandos ejecutados
-const commandLogs = await erlc.getCommandLogs(serverToken);
+const commandLogs = await client.getCommandLogs();
 
 // Logs de Llamadas a Moderadores
-const modCalls = await erlc.getModcallLogs(serverToken);
+const modCalls = await client.getModcallLogs();
 ```
 
 ### 🛠️ Gestión y Administración
 
 ```javascript
 // Ver lista de Baneos
-const bans = await erlc.getBans(serverToken);
+const bans = await client.getBans();
 
 // Obtener Staff del servidor
-const staff = await erlc.getStaff(serverToken);
+const staff = await client.getStaff();
+
+// Obtener cola del servidor
+const queue = await client.getQueue();
 ```
 
 ### 📢 Otros Comandos
 
 ```javascript
 // Ejecutar comando remoto (Ej: Anuncio)
-await erlc.runCommand(serverToken, ":h ¡Hola desde la API!");
+await client.runCommand(":h ¡Hola desde la API!");
 
 // Resetear Global Key (Solo si tienes una configurada)
 // await erlc.resetGlobalKey();
 ```
 
+### Uso con Token Manual
+
+También puedes seguir pasando la server key directamente si prefieres el estilo anterior:
+
+```javascript
+const server = await erlc.getServer("tu-server-key-aqui");
+const players = await erlc.getPlayers("tu-server-key-aqui");
+```
+
 ---
 
 ## 🚨 Manejo de Errores
@@ -133,7 +152,8 @@ La librería lanza errores descriptivos (`ErlcError`) que facilitan la depuraci
 
 ```javascript
 try {
-  await erlc.getServer(serverToken);
+  const client = new erlc.Client({ serverToken: "token-invalido" });
+  await client.connect();
 } catch (error) {
   console.error(`Error ${error.code}: ${error.message}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erlc-api",
-  "version": "3.3.2a",
+  "version": "3.3.3",
   "description": "An ER:LC API wrapper for JS/TS",
   "main": "index.js",
   "types": "src/types/index.d.ts",

package/src/classes/client.js

@@ -1,9 +1,23 @@
 const erlc = require("../erlc.js");
-const assert = require("../functions/assert.js");
+const getBans = require("../functions/server/getBans.js");
+const getCommandLogs = require("../functions/server/getCommandLogs.js");
+const getEmergencyCalls = require("../functions/server/getEmergencyCalls.js");
+const getJoinLogs = require("../functions/server/getJoinLogs.js");
+const getKillLogs = require("../functions/server/getKillLogs.js");
+const getModcallLogs = require("../functions/server/getModcallLogs.js");
+const getPlayers = require("../functions/server/getPlayers.js");
+const getQueue = require("../functions/server/getQueue.js");
+const getServer = require("../functions/server/getServer.js");
+const getStaff = require("../functions/server/getStaff.js");
+const getVehicles = require("../functions/server/getVehicles.js");
+const runCommand = require("../functions/server/runCommand.js");
+const { requestServer } = require("../functions/server/requestServer.js");
 
 /**
  * @typedef {Object} ClientConfig
  * @property {string} [globalToken] - Your ER:LC global API token
+ * @property {string} [serverToken] - Your ER:LC private server API token
+ * @property {boolean} [validateServerToken] - Validate the server token on init
  * @property {Object} [cache] - Cache configuration
  * @property {boolean} [cache.enabled] - Enable in-memory cache
  * @property {Object.<string, number>} [cache.ttlMs] - Per-endpoint TTL in ms
@@ -29,7 +43,12 @@ class Client {
     } else {
       this.options = {};
     }
+    this.connected = false;
+    this.connectionError = null;
     this.config();
+    this.ready = this.options.serverToken && this.options.validateServerToken !== false
+      ? this.connect({ throwOnError: false })
+      : Promise.resolve(this);
   }
 
   /**
@@ -38,13 +57,96 @@ class Client {
    */
   config() {
     // Mutate existing config object to preserve references
-    erlc.config.globalToken = this.options.globalToken;
-    erlc.config.serverToken = this.options.serverToken;
-    erlc.config.cache = this.options.cache;
-    erlc.config.logger = this.options.logger;
-    erlc.config.fetch = this.options.fetch;
+    if (Object.prototype.hasOwnProperty.call(this.options, "globalToken")) {
+      erlc.config.globalToken = this.options.globalToken;
+    }
+    if (Object.prototype.hasOwnProperty.call(this.options, "serverToken")) {
+      erlc.config.serverToken = this.options.serverToken;
+    }
+    if (Object.prototype.hasOwnProperty.call(this.options, "cache")) {
+      erlc.config.cache = this.options.cache;
+    }
+    if (Object.prototype.hasOwnProperty.call(this.options, "logger")) {
+      erlc.config.logger = this.options.logger;
+    }
+    if (Object.prototype.hasOwnProperty.call(this.options, "fetch")) {
+      erlc.config.fetch = this.options.fetch;
+    }
     return erlc.config;
   }
+
+  async connect(options = {}) {
+    const { throwOnError = true } = options;
+
+    try {
+      await requestServer(this.options.serverToken, {
+        endpoint: "server",
+        useCache: false,
+      });
+
+      this.connected = true;
+      this.connectionError = null;
+      erlc.config.logger?.info?.("ER:LC client connected to server.");
+    } catch (error) {
+      this.connected = false;
+      this.connectionError = error;
+      erlc.config.logger?.error?.("ER:LC client failed to connect:", error);
+
+      if (throwOnError) {
+        throw error;
+      }
+    }
+
+    return this;
+  }
+
+  getServer(options = {}) {
+    return getServer(this.options.serverToken, options);
+  }
+
+  getPlayers() {
+    return getPlayers(this.options.serverToken);
+  }
+
+  getVehicles() {
+    return getVehicles(this.options.serverToken);
+  }
+
+  getEmergencyCalls() {
+    return getEmergencyCalls(this.options.serverToken);
+  }
+
+  getJoinLogs() {
+    return getJoinLogs(this.options.serverToken);
+  }
+
+  getKillLogs() {
+    return getKillLogs(this.options.serverToken);
+  }
+
+  getCommandLogs() {
+    return getCommandLogs(this.options.serverToken);
+  }
+
+  getModcallLogs() {
+    return getModcallLogs(this.options.serverToken);
+  }
+
+  getBans() {
+    return getBans(this.options.serverToken);
+  }
+
+  getStaff() {
+    return getStaff(this.options.serverToken);
+  }
+
+  getQueue() {
+    return getQueue(this.options.serverToken);
+  }
+
+  runCommand(command) {
+    return runCommand(this.options.serverToken, command);
+  }
 }
 
 module.exports = Client;

package/src/functions/server/getServer.js

@@ -37,6 +37,11 @@ function normalizeIncludes(options = {}) {
 }
 
 module.exports = (serverToken, options = {}) => {
+  if (serverToken && typeof serverToken === "object") {
+    options = serverToken;
+    serverToken = undefined;
+  }
+
   const includes = normalizeIncludes(options);
 
   return requestServer(serverToken, {

package/src/functions/server/requestServer.js

@@ -8,6 +8,12 @@ function assertServerToken(serverToken) {
   }
 }
 
+function resolveServerToken(serverToken, config) {
+  const resolvedToken = serverToken || config?.serverToken;
+  assertServerToken(resolvedToken);
+  return resolvedToken;
+}
+
 function buildHeaders(serverToken, config, extraHeaders = {}) {
   const headers = {
     "Server-Key": serverToken,
@@ -72,21 +78,21 @@ async function requestJson(url, options) {
 }
 
 async function requestServer(serverToken, options = {}) {
-  assertServerToken(serverToken);
-
   const {
     endpoint = "server",
     includes = [],
     defaultValue = {},
     transform = (data) => data,
+    useCache = true,
   } = options;
 
   const { fetch, config } = await getFetch();
-  const useCache = !!config?.cache?.enabled;
+  const resolvedToken = resolveServerToken(serverToken, config);
+  const shouldCache = useCache && !!config?.cache?.enabled;
   const cacheExtras = includes.length ? includes.join(",") : "";
-  const key = cache.makeKey(endpoint, serverToken, cacheExtras);
+  const key = cache.makeKey(endpoint, resolvedToken, cacheExtras);
 
-  if (useCache) {
+  if (shouldCache) {
     const cached = cache.get(key);
     if (cached) {
       return cached;
@@ -96,14 +102,14 @@ async function requestServer(serverToken, options = {}) {
   const data = await requestJson(buildServerUrl(includes), {
     fetch,
     init: {
-      headers: buildHeaders(serverToken, config),
+      headers: buildHeaders(resolvedToken, config),
       timeout: 10000,
     },
   });
 
   const value = (await transform(data)) ?? defaultValue;
 
-  if (useCache) {
+  if (shouldCache) {
     const ttlMs = cache.getTTL(endpoint, config);
     cache.set(key, value, ttlMs);
   }
@@ -112,8 +118,6 @@ async function requestServer(serverToken, options = {}) {
 }
 
 async function requestApi(serverToken, path, options = {}) {
-  assertServerToken(serverToken);
-
   const {
     baseUrl = BASEURL,
     method = "GET",
@@ -126,8 +130,9 @@ async function requestApi(serverToken, path, options = {}) {
   } = options;
 
   const { fetch, config } = await getFetch();
+  const resolvedToken = resolveServerToken(serverToken, config);
   const shouldCache = method === "GET" && useCache && !!config?.cache?.enabled;
-  const key = cache.makeKey(endpoint, serverToken);
+  const key = cache.makeKey(endpoint, resolvedToken);
 
   if (shouldCache) {
     const cached = cache.get(key);
@@ -137,7 +142,7 @@ async function requestApi(serverToken, path, options = {}) {
   }
 
   const headers = buildHeaders(
-    serverToken,
+    resolvedToken,
     config,
     body ? { "Content-Type": "application/json" } : {},
   );
@@ -171,6 +176,7 @@ async function requestLegacyServer(serverToken, path, options = {}) {
 
 module.exports = {
   assertServerToken,
+  resolveServerToken,
   buildHeaders,
   getFetch,
   requestServer,

package/src/functions/server/runCommand.js

@@ -1,4 +1,4 @@
-const { assertServerToken, requestApi } = require("./requestServer.js");
+const { requestApi } = require("./requestServer.js");
 
 /**
  * Executes a command on the server.
@@ -7,7 +7,10 @@ const { assertServerToken, requestApi } = require("./requestServer.js");
  * @returns {Promise<boolean>} Promise that resolves to true if command was executed successfully
  */
 module.exports = async (serverToken, command) => {
-  assertServerToken(serverToken);
+  if (command === undefined) {
+    command = serverToken;
+    serverToken = undefined;
+  }
 
   if (!command || typeof command !== "string") {
     throw new Error("Command is required and must be a string");

package/src/types/index.d.ts

@@ -32,6 +32,8 @@ export interface ErrorInfo {
 
 export interface ClientConfig {
   globalToken?: string; // The ER:LC global API token
+  serverToken?: string; // The ER:LC private server API token
+  validateServerToken?: boolean; // Validate serverToken with /server on init
   cache?: {
     enabled?: boolean;
     ttlMs?: Record<string, number>;
@@ -166,30 +168,49 @@ export interface VSMCommandBody {
   command: string; // ":h Hey everyone!"
 }
 
-export function getBans(serverToken: string): Promise<ServerBan>;
-export function getCommandLogs(serverToken: string): Promise<CommandLog[]>;
-export function getJoinLogs(serverToken: string): Promise<JoinLog[]>;
-export function getKillLogs(serverToken: string): Promise<KillLog[]>;
-export function getModcallLogs(serverToken: string): Promise<ModcallLog[]>;
-export function getEmergencyCalls(serverToken: string): Promise<EmergencyCall[]>;
-export function getPlayers(serverToken: string): Promise<ServerPlayer[]>;
-export function getQueue(serverToken: string): Promise<number[]>;
+export function getBans(serverToken?: string): Promise<ServerBan>;
+export function getCommandLogs(serverToken?: string): Promise<CommandLog[]>;
+export function getJoinLogs(serverToken?: string): Promise<JoinLog[]>;
+export function getKillLogs(serverToken?: string): Promise<KillLog[]>;
+export function getModcallLogs(serverToken?: string): Promise<ModcallLog[]>;
+export function getEmergencyCalls(serverToken?: string): Promise<EmergencyCall[]>;
+export function getPlayers(serverToken?: string): Promise<ServerPlayer[]>;
+export function getQueue(serverToken?: string): Promise<number[]>;
 export function getServer(
-  serverToken: string,
+  serverToken?: string,
   options?: ServerIncludeOptions,
 ): Promise<ServerStatus>;
-export function getStaff(serverToken: string): Promise<ServerStaff>;
-export function getVehicles(serverToken: string): Promise<VehiclesLog[]>;
+export function getServer(options?: ServerIncludeOptions): Promise<ServerStatus>;
+export function getStaff(serverToken?: string): Promise<ServerStaff>;
+export function getVehicles(serverToken?: string): Promise<VehiclesLog[]>;
 export function runCommand(
   serverToken: string,
   command: string,
 ): Promise<boolean>;
+export function runCommand(command: string): Promise<boolean>;
 
 export function resetGlobalKey(): Promise<any>;
 
 export class Client {
+  connected: boolean;
+  connectionError: Error | null;
+  ready: Promise<Client>;
+
   constructor(options?: ClientConfig);
   config(): ClientConfig;
+  connect(options?: { throwOnError?: boolean }): Promise<Client>;
+  getServer(options?: ServerIncludeOptions): Promise<ServerStatus>;
+  getPlayers(): Promise<ServerPlayer[]>;
+  getVehicles(): Promise<VehiclesLog[]>;
+  getEmergencyCalls(): Promise<EmergencyCall[]>;
+  getJoinLogs(): Promise<JoinLog[]>;
+  getKillLogs(): Promise<KillLog[]>;
+  getCommandLogs(): Promise<CommandLog[]>;
+  getModcallLogs(): Promise<ModcallLog[]>;
+  getBans(): Promise<ServerBan>;
+  getStaff(): Promise<ServerStaff>;
+  getQueue(): Promise<number[]>;
+  runCommand(command: string): Promise<boolean>;
 }
 
 export const utils: {

package/tests/cache.test.js

@@ -21,6 +21,8 @@ describe("Optional cache", () => {
   beforeEach(() => {
     fetchCalls = 0;
     lastUrl = "";
+    erlc.config.serverToken = undefined;
+    erlc.config.globalToken = undefined;
     erlc.config.cache.enabled = false;
     erlc.config.fetch = mockFetch;
   });
@@ -43,4 +45,57 @@ describe("Optional cache", () => {
     expect(Array.isArray(res2)).toBe(true);
     expect(fetchCalls).toBe(1);
   });
+
+  test("Client validates server token on init", async () => {
+    let lastHeaders = {};
+    const logger = {
+      info: jest.fn(),
+      error: jest.fn(),
+    };
+
+    erlc.config.fetch = async (url, opts) => {
+      fetchCalls += 1;
+      lastUrl = url;
+      lastHeaders = opts.headers;
+
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ Name: "Test Server" }),
+      };
+    };
+
+    const client = new erlc.Client({
+      serverToken,
+      fetch: erlc.config.fetch,
+      logger,
+    });
+
+    expect(client.connected).toBe(false);
+
+    await client.ready;
+
+    expect(client.connected).toBe(true);
+    expect(client.connectionError).toBe(null);
+    expect(lastUrl).toBe("https://api.erlc.gg/v2/server");
+    expect(lastHeaders["Server-Key"]).toBe(serverToken);
+    expect(logger.info).toHaveBeenCalledWith("ER:LC client connected to server.");
+    expect(fetchCalls).toBe(1);
+  });
+
+  test("Client stores server token for instance methods and global fallback", async () => {
+    const client = new erlc.Client({
+      serverToken,
+      fetch: mockFetch,
+      validateServerToken: false,
+    });
+
+    const clientPlayers = await client.getPlayers();
+    const fallbackPlayers = await erlc.getPlayers();
+
+    expect(Array.isArray(clientPlayers)).toBe(true);
+    expect(Array.isArray(fallbackPlayers)).toBe(true);
+    expect(fetchCalls).toBe(2);
+    expect(lastUrl).toBe("https://api.erlc.gg/v2/server?Players=true");
+  });
 });