erlc-api 3.3.0 → 3.3.2-a

package/README.md

@@ -4,40 +4,42 @@
 [![License](https://img.shields.io/npm/l/erlc-api?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/npm/dt/erlc-api?style=flat-square)](https://www.npmjs.com/package/erlc-api)
 
-Una librería ligera, completa y **totalmente tipada** para interactuar con la API de *Emergency Response: Liberty County* (ER:LC). Diseñada para ofrecer la mejor experiencia de desarrollo tanto en JavaScript como en TypeScript.
+[🇪🇸 Versión en Español](README_ES.md)
+
+A lightweight, complete, and **fully typed** library for interacting with the *Emergency Response: Liberty County* (ER:LC) API. Designed to provide the best development experience in both JavaScript and TypeScript.
 
 ---
 
-## ✨ Características
+## ✨ Features
 
-- 🎯 **Cobertura Total**: Soporte para el 100% de los endpoints de la API v1.
-- 🛡️ **Tipado TypeScript**: Definiciones de tipos incluidas nativamente.
-- ⚡ **Ligero y Rápido**: Sin dependencias pesadas innecesarias.
-- 🔒 **Seguro**: Validación de tokens y manejo de errores robusto.
-- 🆕 **Actualizado**: Soporte para `GlobalToken` opcional (v3.2.0+).
+- 🎯 **Current API Support**: Uses `https://api.erlc.gg/v2` where available.
+- 🛡️ **TypeScript Support**: Native type definitions included.
+- ⚡ **Lightweight & Fast**: No unnecessary heavy dependencies.
+- 🔒 **Secure**: Robust token validation and error handling.
+- 🆕 **Up-to-date**: Supports optional global API keys for large-scale apps.
 
-## 📦 Instalación
+## 📦 Installation
 
 ```bash
 npm install erlc-api
-# o
+# or
 bun add erlc-api
 ```
 
-## 🚀 Inicio Rápido
+## 🚀 Quick Start
 
-### Inicialización
+### Initialization
 
-Puedes usar la librería con o sin un `Global Token` (requerido solo para aplicaciones a gran escala).
+You can use the library with or without a `Global Token` (required only for large-scale applications).
 
 **JavaScript**
 ```javascript
 const erlc = require("erlc-api");
 
-// Inicialización simple (Recomendada para la mayoría)
+// Simple initialization (Recommended for most users)
 const client = new erlc.Client();
 
-// O con Global Token (Para Large Apps)
+// Or with Global Token (For Large Apps)
 // const client = new erlc.Client({ globalToken: "..." });
 ```
 
@@ -50,97 +52,104 @@ const client = new Client();
 
 ---
 
-## 📖 Ejemplos de Uso
+## 📖 Usage Examples
 
-Asegúrate de tener tu `Server Key` a mano (obtenla en los ajustes de tu servidor privado en ER:LC).
+Make sure to have your `Server Key` ready (get it from your private server settings in ER:LC).
 
-### 🖥️ Información del Servidor
+### 🖥️ Server Information
 
 ```javascript
-const serverToken = "tu-server-key-aqui";
+const serverToken = "your-server-key-here";
 
-// Obtener estado del servidor
+// Get server status
 const server = await erlc.getServer(serverToken);
-console.log(`Servidor: ${server.Name} | Jugadores: ${server.CurrentPlayers}/${server.MaxPlayers}`);
+console.log(`Server: ${server.Name} | Players: ${server.CurrentPlayers}/${server.MaxPlayers}`);
 
-// Obtener jugadores conectados
+// Get connected players
 const players = await erlc.getPlayers(serverToken);
-console.table(players); // Muestra nombre, ID, permisos y equipo
+console.table(players); // Shows name, ID, permission, and team
 
-// Obtener vehículos en el mapa
+// Get vehicles on the map
 const vehicles = await erlc.getVehicles(serverToken);
+
+// Get emergency calls
+const emergencyCalls = await erlc.getEmergencyCalls(serverToken);
+
+// Fetch server info with v2 include flags in one request
+const fullServer = await erlc.getServer(serverToken, {
+  players: true,
+  staff: true,
+  emergencyCalls: true,
+});
 ```
 
-### 📜 Registros (Logs)
+### 📜 Logs
 
-Accede a los historiales de actividad de tu servidor:
+Access your server's activity history:
 
 ```javascript
-// Logs de Entradas/Salidas
+// Join/Leave Logs
 const joinLogs = await erlc.getJoinLogs(serverToken);
 
-// Logs de Muertes (Killfeed)
+// Kill Logs (Killfeed)
 const killLogs = await erlc.getKillLogs(serverToken);
 
-// Logs de Comandos ejecutados
+// Command Logs
 const commandLogs = await erlc.getCommandLogs(serverToken);
 
-// Logs de Llamadas a Moderadores
+// Mod Call Logs
 const modCalls = await erlc.getModcallLogs(serverToken);
 ```
 
-### 🛠️ Gestión y Administración
+### 🛠️ Management & Administration
 
 ```javascript
-// Ver lista de Baneos
+// Get Ban List
 const bans = await erlc.getBans(serverToken);
 
-// Obtener Staff del servidor
+// Get Server Staff
 const staff = await erlc.getStaff(serverToken);
 
-// Ejecutar comando remoto (Ej: Anuncio)
-await erlc.runCommand(serverToken, ":h ¡Hola desde la API!");
+// Get Queue
+const queue = await erlc.getQueue(serverToken);
+```
+
+### ⚡ Run Command
 
-// Resetear Global Key (Solo si tienes una configurada)
-// await erlc.resetGlobalKey();
+Execute commands directly from your code:
+
+```javascript
+const command = await erlc.runCommand(serverToken, ":announce This is an API test!");
+console.log(command); // Returns true if successful
 ```
 
 ---
 
-## 🚨 Manejo de Errores
+## ⚠️ Error Handling
 
-La librería lanza errores descriptivos (`ErlcError`) que facilitan la depuración.
+The library throws descriptive errors. You should wrap your calls in `try/catch` blocks.
 
 ```javascript
 try {
-  await erlc.getServer(serverToken);
+  const data = await erlc.getServer("invalid-token");
 } catch (error) {
-  console.error(`Error ${error.code}: ${error.message}`);
-  
-  if (error.code === 4001) console.log("⏳ Rate limit alcanzado, espera un momento.");
-  if (error.code === 2002) console.log("🔑 La Server Key es inválida o expiró.");
+  console.error(error.message); // e.g., "Forbidden: Access denied..."
 }
 ```
 
-### Códigos Comunes
-
-| Código | Significado | Solución |
-|:---:|---|---|
-| **2002** | Key Inválida | Verifica tu `Server-Key` en el juego. |
-| **3002** | Servidor Offline | El servidor no tiene jugadores o está apagado. |
-| **4001** | Rate Limit | Estás enviando muchas peticiones muy rápido. |
-| **403** | No Autorizado | Verifica tus permisos o tokens. |
+| Error Code | Description |
+|------------|-------------|
+| `2002` | Invalid or expired server key |
+| `3002` | Server offline |
+| `4001` | Rate limit exceeded |
+| `9999` | In-game server module is out of date |
 
 ---
 
-## 🔗 Enlaces Útiles
+## 🤝 Contributing
 
-- [Documentación Oficial de PRC](https://apidocs.policeroleplay.community/)
-- [Discord de Soporte PRC](https://discord.gg/prc)
-- [NPM Package](https://www.npmjs.com/package/erlc-api)
+Contributions are welcome! Feel free to submit a Pull Request.
 
----
+## 📄 License
 
-<div align="center">
-  <sub>Hecho con ❤️ para la comunidad de ER:LC</sub>
-</div>
+This project is licensed under the [MIT License](LICENSE).

package/README_ES.md

@@ -0,0 +1,168 @@
+# 🚔 ER:LC API Wrapper
+
+[![npm version](https://img.shields.io/npm/v/erlc-api?style=flat-square)](https://www.npmjs.com/package/erlc-api)
+[![License](https://img.shields.io/npm/l/erlc-api?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/npm/dt/erlc-api?style=flat-square)](https://www.npmjs.com/package/erlc-api)
+
+[🇬🇧 English Version](README.md)
+
+Una librería ligera, completa y **totalmente tipada** para interactuar con la API de _Emergency Response: Liberty County_ (ER:LC). Diseñada para ofrecer la mejor experiencia de desarrollo tanto en JavaScript como en TypeScript.
+
+---
+
+## ✨ Características
+
+- 🎯 **Soporte API Actual**: Usa `https://api.erlc.gg/v2` donde está disponible.
+- 🛡️ **Tipado TypeScript**: Definiciones de tipos incluidas nativamente.
+- ⚡ **Ligero y Rápido**: Sin dependencias pesadas innecesarias.
+- 🔒 **Seguro**: Validación de tokens y manejo de errores robusto.
+- 🆕 **Actualizado**: Soporte para global API keys opcionales en apps grandes.
+
+## 📦 Instalación
+
+```bash
+npm install erlc-api
+# o
+bun add erlc-api
+```
+
+## 🚀 Inicio Rápido
+
+### Inicialización
+
+Puedes usar la librería con o sin un `Global Token` (requerido solo 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();
+
+// O con Global Token (Para Large Apps)
+// const client = new erlc.Client({ globalToken: "..." });
+```
+
+**TypeScript**
+
+```typescript
+import { Client, getServer } from "erlc-api";
+
+const client = new Client();
+```
+
+---
+
+## 📖 Ejemplos de Uso
+
+Asegúrate de tener tu `Server Key` a mano (obtenla en los ajustes de tu servidor privado en ER:LC).
+
+### 🖥️ Información del Servidor
+
+```javascript
+const serverToken = "tu-server-key-aqui";
+
+// Obtener estado del servidor
+const server = await erlc.getServer(serverToken);
+console.log(
+  `Servidor: ${server.Name} | Jugadores: ${server.CurrentPlayers}/${server.MaxPlayers}`,
+);
+
+// Obtener jugadores conectados
+const players = await erlc.getPlayers(serverToken);
+console.table(players); // Muestra nombre, ID, permisos y equipo
+
+// Obtener vehículos en el mapa
+const vehicles = await erlc.getVehicles(serverToken);
+
+// Obtener llamadas de emergencia
+const emergencyCalls = await erlc.getEmergencyCalls(serverToken);
+
+// Obtener información del servidor con includes de v2 en una sola petición
+const fullServer = await erlc.getServer(serverToken, {
+  players: true,
+  staff: true,
+  emergencyCalls: true,
+});
+```
+
+### 📜 Registros (Logs)
+
+Accede a los historiales de actividad de tu servidor:
+
+```javascript
+// Logs de Entradas/Salidas
+const joinLogs = await erlc.getJoinLogs(serverToken);
+
+// Logs de Muertes (Killfeed)
+const killLogs = await erlc.getKillLogs(serverToken);
+
+// Logs de Comandos ejecutados
+const commandLogs = await erlc.getCommandLogs(serverToken);
+
+// Logs de Llamadas a Moderadores
+const modCalls = await erlc.getModcallLogs(serverToken);
+```
+
+### 🛠️ Gestión y Administración
+
+```javascript
+// Ver lista de Baneos
+const bans = await erlc.getBans(serverToken);
+
+// Obtener Staff del servidor
+const staff = await erlc.getStaff(serverToken);
+```
+
+### 📢 Otros Comandos
+
+```javascript
+// Ejecutar comando remoto (Ej: Anuncio)
+await erlc.runCommand(serverToken, ":h ¡Hola desde la API!");
+
+// Resetear Global Key (Solo si tienes una configurada)
+// await erlc.resetGlobalKey();
+```
+
+---
+
+## 🚨 Manejo de Errores
+
+La librería lanza errores descriptivos (`ErlcError`) que facilitan la depuración.
+
+```javascript
+try {
+  await erlc.getServer(serverToken);
+} catch (error) {
+  console.error(`Error ${error.code}: ${error.message}`);
+
+  if (error.code === 4001)
+    console.log("⏳ Rate limit alcanzado, espera un momento.");
+  if (error.code === 2002)
+    console.log("🔑 La Server Key es inválida o expiró.");
+}
+```
+
+### Códigos Comunes
+
+|  Código  | Significado      | Solución                                       |
+| :------: | ---------------- | ---------------------------------------------- |
+| **2002** | Key Inválida     | Verifica tu `Server-Key` en el juego.          |
+| **3002** | Servidor Offline | El servidor no tiene jugadores o está apagado. |
+| **4001** | Rate Limit       | Estás enviando muchas peticiones muy rápido.   |
+| **403**  | No Autorizado    | Verifica tus permisos o tokens.                |
+
+---
+
+## 🔗 Enlaces Útiles
+
+- [Documentación Oficial de ER:LC](https://apidocs.erlc.gg/)
+- [Discord de Soporte PRC](https://discord.gg/prc)
+- [NPM Package](https://www.npmjs.com/package/erlc-api)
+
+---
+
+<div align="center">
+  <sub>Hecho con ❤️ para la comunidad de ER:LC</sub>
+</div>

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "erlc-api",
-  "version": "3.3.0",
+  "version": "3.3.2a",
   "description": "An ER:LC API wrapper for JS/TS",
   "main": "index.js",
   "types": "src/types/index.d.ts",
+  "packageManager": "pnpm@11.1.2",
   "keywords": [
     "erlc",
     "roblox",
@@ -14,16 +15,22 @@
   "author": "egologics",
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^5.3.2"
+    "jest": "^30.4.2",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "chalk": "^5.4.1",
+    "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "node-fetch": "^3.3.2",
-    "ora": "^8.2.0"
+    "ora": "^9.4.0"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "unrs-resolver"
+    ]
   },
   "repository": {
     "type": "git",

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  unrs-resolver: true

package/src/classes/client.js

@@ -3,7 +3,13 @@ const assert = require("../functions/assert.js");
 
 /**
  * @typedef {Object} ClientConfig
- * @property {string} globalToken - Your ER:LC global API token
+ * @property {string} [globalToken] - Your ER:LC global API token
+ * @property {Object} [cache] - Cache configuration
+ * @property {boolean} [cache.enabled] - Enable in-memory cache
+ * @property {Object.<string, number>} [cache.ttlMs] - Per-endpoint TTL in ms
+ * @property {boolean} [cache.staleWhileRevalidate] - Placeholder for future strategy
+ * @property {Object} [logger] - Logger instance (console-compatible)
+ * @property {Function} [fetch] - Custom fetch implementation
  */
 
 /**
@@ -31,7 +37,12 @@ class Client {
    * @returns {ClientConfig} The client configuration.
    */
   config() {
-    erlc.config = this.options;
+    // 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;
     return erlc.config;
   }
 }

package/src/constants.js

@@ -1,2 +1,5 @@
-exports.Vanity = "https://policeroleplay.community/join?code="
-exports.BASEURL = "https://api.policeroleplay.community/v1"
+exports.Vanity = "https://erlc.gg/join/"
+exports.API_ORIGIN = "https://api.erlc.gg"
+exports.API_VERSION = "v2"
+exports.BASEURL = `${exports.API_ORIGIN}/${exports.API_VERSION}`
+exports.LEGACY_BASEURL = `${exports.API_ORIGIN}/v1`

package/src/erlc.js

@@ -1,10 +1,33 @@
-exports.config = {};
+exports.config = {
+  cache: {
+    enabled: false,
+    ttlMs: {
+      server: 10000,
+      players: 3000,
+      vehicles: 5000,
+      joinlogs: 3000,
+      killlogs: 3000,
+      commandlogs: 3000,
+      modcalls: 3000,
+      emergencycalls: 3000,
+      staff: 10000,
+      queue: 2000,
+      bans: 10000,
+    },
+    staleWhileRevalidate: false,
+  },
+  logger: console,
+  fetch: null,
+};
+
+Object.assign(exports, require("./constants.js"));
 
 exports.getBans = require("./functions/server/getBans.js");
 exports.getCommandLogs = require("./functions/server/getCommandLogs.js");
 exports.getJoinLogs = require("./functions/server/getJoinLogs.js");
 exports.getKillLogs = require("./functions/server/getKillLogs.js");
 exports.getModcallLogs = require("./functions/server/getModcallLogs.js");
+exports.getEmergencyCalls = require("./functions/server/getEmergencyCalls.js");
 exports.getPlayers = require("./functions/server/getPlayers.js");
 exports.getServer = require("./functions/server/getServer.js");
 exports.getQueue = require("./functions/server/getQueue.js");
@@ -14,3 +37,8 @@ exports.getStaff = require("./functions/server/getStaff.js");
 exports.resetGlobalKey = require("./functions/global/resetGlobalKey.js");
 
 exports.Client = require("./classes/client.js");
+
+exports.utils = {
+  cache: require("./utils/cache.js"),
+  discord: require("./utils/discord.js"),
+};

package/src/errors/ErlcError.js

@@ -21,6 +21,9 @@ class ErlcError extends Error {
       message: this.message,
       code: this.code,
       status: this.status,
+      retryAfter: this.retryAfter,
+      bucket: this.bucket,
+      commandId: this.commandId,
       timestamp: this.timestamp,
       stack: this.stack,
     };

package/src/functions/global/resetGlobalKey.js

@@ -1,4 +1,4 @@
-const { BASEURL } = require("../../constants.js");
+const { LEGACY_BASEURL } = require("../../constants.js");
 const { processError } = require("../../utils/errorHandler.js");
 
 /**
@@ -8,20 +8,24 @@ const { processError } = require("../../utils/errorHandler.js");
 module.exports = () => {
   return new Promise(async (resolve, reject) => {
     try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
+      const { config } = require("../../erlc.js");
 
       // Check if global token is configured
       if (!config?.globalToken) {
         const error = await processError(
           new Error(
-            "Global token not configured. Please initialize the client first."
-          )
+            "Global token not configured. Please initialize the client first.",
+          ),
         );
         return reject(error);
       }
 
-      const res = await fetch.default(`${BASEURL}/api-key/reset`, {
+      const f =
+        config?.fetch ||
+        (typeof globalThis.fetch === "function"
+          ? globalThis.fetch
+          : (await import("node-fetch")).default);
+      const res = await f(`${LEGACY_BASEURL}/api-key/reset`, {
         method: "POST",
         headers: {
           Authorization: config.globalToken,
@@ -44,13 +48,13 @@ module.exports = () => {
       // However, looking at other endpoints, they return data directly.
       // Let's assume it returns a JSON with the key, or we can inspect the response content type.
       // But for now, let's try to parse as JSON.
-      
+
       const data = await res.json();
       // If data has a specific field for the key, we should return that.
       // If the documentation doesn't specify, I'll return the whole data object or try to find the key.
       // Based on "This will send a new key", it might be { "apiKey": "..." } or just the string if it's text/plain.
       // Given other endpoints return JSON, this likely returns JSON.
-      
+
       resolve(data);
     } catch (error) {
       const processedError = await processError(error);

package/src/functions/server/getBans.js

@@ -1,47 +1,17 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { requestLegacyServer } = require("./requestServer.js");
 
 /**
- * Retrieves the list of banned players from a server
+ * Retrieves the list of banned players from a server.
+ *
+ * The current v2 server document does not expose Bans as an include flag,
+ * so this uses the documented v1 bans route on the new api.erlc.gg domain.
+ *
  * @param {string} serverToken - The server API key
  * @returns {Promise<Object>} Promise that resolves to banned players 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/bans`, {
-        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 || {});
-    } catch (error) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = (serverToken) =>
+  requestLegacyServer(serverToken, "/server/bans", {
+    endpoint: "bans",
+    defaultValue: {},
+    transform: (data) => data || {},
   });
-};