erlc-api 2.3.4 → 3.1.0

package/examples/error-handling.js

@@ -0,0 +1,159 @@
+const erlc = require("../index.js");
+
+// Initialize the client
+const client = new erlc.Client({
+  globalToken: "your-global-token-here",
+});
+
+client.config();
+
+/**
+ * Example of comprehensive error handling with the new ERLC error system
+ */
+async function demonstrateErrorHandling() {
+  const serverToken = "your-server-token-here";
+
+  try {
+    // This might fail with various ERLC error codes
+    const serverInfo = await erlc.getServer(serverToken);
+    console.log("✅ Server info retrieved successfully:", serverInfo.Name);
+  } catch (error) {
+    // The error is now an ErlcError instance with detailed information
+    console.error("❌ Error occurred:");
+    console.error(`Code: ${error.code}`);
+    console.error(`Message: ${error.message}`);
+    console.error(`Category: ${error.category}`);
+    console.error(`Severity: ${error.severity}`);
+
+    if (error.suggestions) {
+      console.error("💡 Suggested actions:");
+      error.suggestions.forEach((suggestion, index) => {
+        console.error(`   ${index + 1}. ${suggestion}`);
+      });
+    }
+
+    if (error.retryable) {
+      console.error("🔄 This error might be resolved by retrying");
+    }
+
+    // Handle specific error codes
+    switch (error.code) {
+      case 2002:
+        console.error(
+          "🔑 Your server key is invalid or expired. Please get a new one from your server settings."
+        );
+        break;
+      case 4001:
+        console.error(
+          "⏱️ You're being rate limited. Waiting 60 seconds before retry..."
+        );
+        // Implement retry logic here
+        break;
+      case 3002:
+        console.error(
+          "🏃 Server is offline (no players). Waiting for players to join..."
+        );
+        break;
+      case 9999:
+        console.error(
+          "🔄 Server module is outdated. Please kick all players and restart the server."
+        );
+        break;
+      default:
+        console.error("🤔 Unexpected error occurred");
+    }
+  }
+}
+
+/**
+ * Example of handling multiple API calls with proper error handling
+ */
+async function handleMultipleApiCalls() {
+  const serverToken = "your-server-token-here";
+
+  const apiCalls = [
+    { name: "Server Info", call: () => erlc.getServer(serverToken) },
+    { name: "Players", call: () => erlc.getPlayers(serverToken) },
+    { name: "Staff", call: () => erlc.getStaff(serverToken) },
+    { name: "Vehicles", call: () => erlc.getVehicles(serverToken) },
+  ];
+
+  for (const { name, call } of apiCalls) {
+    try {
+      const result = await call();
+      console.log(`✅ ${name}: Success`);
+    } catch (error) {
+      console.error(`❌ ${name}: Failed`);
+      console.error(`   Code: ${error.code}`);
+      console.error(`   Message: ${error.message}`);
+
+      // Skip retryable errors for this example
+      if (!error.retryable) {
+        console.error(`   This is a non-retryable error, stopping execution`);
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Example of implementing retry logic for retryable errors
+ */
+async function withRetry(apiCall, maxRetries = 3, delayMs = 1000) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await apiCall();
+    } catch (error) {
+      console.error(`Attempt ${attempt} failed:`, error.message);
+
+      if (!error.retryable || attempt === maxRetries) {
+        throw error; // Don't retry non-retryable errors or if max retries reached
+      }
+
+      // Wait before retrying (exponential backoff)
+      const delay = delayMs * Math.pow(2, attempt - 1);
+      console.log(`Waiting ${delay}ms before retry...`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+/**
+ * Example usage of retry logic
+ */
+async function demonstrateRetryLogic() {
+  const serverToken = "your-server-token-here";
+
+  try {
+    const players = await withRetry(() => erlc.getPlayers(serverToken));
+    console.log("✅ Players retrieved successfully:", players.length);
+  } catch (error) {
+    console.error("❌ Failed after all retries:", error.message);
+
+    if (error.suggestions) {
+      console.error("💡 Try these suggestions:");
+      error.suggestions.forEach((suggestion) =>
+        console.error(`   - ${suggestion}`)
+      );
+    }
+  }
+}
+
+// Run examples
+if (require.main === module) {
+  console.log("🚀 ERLC API Error Handling Examples\n");
+
+  demonstrateErrorHandling()
+    .then(() => console.log("\n" + "=".repeat(50) + "\n"))
+    .then(() => handleMultipleApiCalls())
+    .then(() => console.log("\n" + "=".repeat(50) + "\n"))
+    .then(() => demonstrateRetryLogic())
+    .catch(console.error);
+}
+
+module.exports = {
+  demonstrateErrorHandling,
+  handleMultipleApiCalls,
+  withRetry,
+  demonstrateRetryLogic,
+};

package/package.json

@@ -1,34 +1,36 @@
-{
-  "name": "erlc-api",
-  "version": "2.3.4",
-  "description": "An ER:LC API wrapper for JS/TS",
-  "main": "index.js",
-  "types": "src/types/index.d.ts",
-  "keywords": [
-    "erlc",
-    "roblox",
-    "prc",
-    "erlc-api",
-    "liberty-county"
-  ],
-  "author": "egologics",
-  "license": "MIT",
-  "devDependencies": {
-    "typescript": "^5.3.2"
-  },
-  "dependencies": {
-    "erlc-api": "file:",
-    "node-fetch": "^3.3.2"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Exodo0/ERLC-API.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Exodo0/ERLC-API/issues"
-  },
-  "homepage": "https://github.com/Exodo0/ERLC-API#readme"
-}
+{
+  "name": "erlc-api",
+  "version": "3.1.0",
+  "description": "An ER:LC API wrapper for JS/TS",
+  "main": "index.js",
+  "types": "src/types/index.d.ts",
+  "keywords": [
+    "erlc",
+    "roblox",
+    "prc",
+    "erlc-api",
+    "liberty-county"
+  ],
+  "author": "egologics",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.2"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.2.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Exodo0/ERLC-API.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Exodo0/ERLC-API/issues"
+  },
+  "homepage": "https://github.com/Exodo0/ERLC-API#readme"
+}

package/src/classes/client.js

@@ -1,36 +1,36 @@
-const erlc = require('../erlc.js')
-const assert = require('../functions/assert.js')
-
-/**
- * @typedef {Object} ClientConfig
- * @property {string} globalToken - Your ER:LC global API token
- */
-
-/**
- * Creates an authorised ER:LC client for requests
- * @class
- * @param {ClientConfig} options - Client Options
- */
-
-class Client {
-
-    /**
-     * @constructor
-     * @param {ClientConfig} options - Client Options
-     */
-    constructor(options) {
-        assert(typeof options === 'object', `Syntax error: object expected for "options", received ${typeof options}`);
-        this.options = { ...options };
-      }
-    
-     /**
-     * Updates and returns the client configurationg
-     * @returns {ClientConfig} The client configuration.
-     */
-    config() {
-        erlc.config = this.options
-        return erlc.config
-    }
-}
-
+const erlc = require('../erlc.js')
+const assert = require('../functions/assert.js')
+
+/**
+ * @typedef {Object} ClientConfig
+ * @property {string} globalToken - Your ER:LC global API token
+ */
+
+/**
+ * Creates an authorised ER:LC client for requests
+ * @class
+ * @param {ClientConfig} options - Client Options
+ */
+
+class Client {
+
+    /**
+     * @constructor
+     * @param {ClientConfig} options - Client Options
+     */
+    constructor(options) {
+        assert(typeof options === 'object', `Syntax error: object expected for "options", received ${typeof options}`);
+        this.options = { ...options };
+      }
+    
+     /**
+     * Updates and returns the client configurationg
+     * @returns {ClientConfig} The client configuration.
+     */
+    config() {
+        erlc.config = this.options
+        return erlc.config
+    }
+}
+
 module.exports = Client

package/src/constants.js

@@ -1,2 +1,2 @@
-exports.Vanity = "https://policeroleplay.community/join?code="
+exports.Vanity = "https://policeroleplay.community/join?code="
 exports.BASEURL = "https://api.policeroleplay.community/v1"

package/src/erlc.js

@@ -1,14 +1,15 @@
-exports.config = {};
-
-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.getPlayers = require("./functions/server/getPlayers.js");
-exports.getServer = require("./functions/server/getServer.js");
-exports.getQueue = require("./functions/server/getQueue.js");
-exports.runCommand = require("./functions/server/runCommand.js");
-exports.getVehicles = require("./functions/server/getVehicles.js");
-
-exports.Client = require("./classes/client.js");
+exports.config = {};
+
+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.getPlayers = require("./functions/server/getPlayers.js");
+exports.getServer = require("./functions/server/getServer.js");
+exports.getQueue = require("./functions/server/getQueue.js");
+exports.runCommand = require("./functions/server/runCommand.js");
+exports.getVehicles = require("./functions/server/getVehicles.js");
+exports.getStaff = require("./functions/server/getStaff.js");
+
+exports.Client = require("./classes/client.js");

package/src/errors/ErlcError.js

@@ -0,0 +1,34 @@
+class ErlcError extends Error {
+  constructor(message, code, status, originalError = null) {
+    super(message);
+    this.name = "ErlcError";
+    this.code = code;
+    this.status = status;
+    this.originalError = originalError;
+    this.timestamp = new Date().toISOString();
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ErlcError);
+    }
+  }
+
+  /**
+   * Returns a JSON representation of the error
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.status,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    };
+  }
+
+  toString() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+}
+
+module.exports = ErlcError;

package/src/errors/errorCodes.js

@@ -0,0 +1,218 @@
+const ERLC_ERROR_CODES = {
+  // System Errors (0-999)
+  0: {
+    message: "Unknown error occurred",
+    description:
+      "An unexpected error happened. If this persists, contact PRC via an API ticket.",
+    category: "SYSTEM_ERROR",
+    severity: "HIGH",
+  },
+
+  // Communication Errors (1000-1999)
+  1001: {
+    message: "Communication error with Roblox server",
+    description:
+      "Failed to communicate with Roblox or the in-game private server. The server may be experiencing issues.",
+    category: "COMMUNICATION_ERROR",
+    severity: "HIGH",
+  },
+  1002: {
+    message: "Internal system error",
+    description: "An internal system error occurred on the ERLC API servers.",
+    category: "SYSTEM_ERROR",
+    severity: "HIGH",
+  },
+
+  // Authentication Errors (2000-2999)
+  2000: {
+    message: "Missing server key",
+    description: "You must provide a valid server-key header in your request.",
+    category: "AUTHENTICATION_ERROR",
+    severity: "HIGH",
+  },
+  2001: {
+    message: "Invalid server key format",
+    description: "The server-key you provided is incorrectly formatted.",
+    category: "AUTHENTICATION_ERROR",
+    severity: "HIGH",
+  },
+  2002: {
+    message: "Invalid or expired server key",
+    description:
+      "The server-key you provided is invalid or has expired. Please check your server settings.",
+    category: "AUTHENTICATION_ERROR",
+    severity: "HIGH",
+  },
+  2003: {
+    message: "Invalid global API key",
+    description:
+      "The global API key you provided is invalid. Please check your client configuration.",
+    category: "AUTHENTICATION_ERROR",
+    severity: "HIGH",
+  },
+  2004: {
+    message: "Server key banned",
+    description:
+      "Your server-key has been banned from accessing the API. Contact PRC support for assistance.",
+    category: "AUTHENTICATION_ERROR",
+    severity: "CRITICAL",
+  },
+
+  // Request Errors (3000-3999)
+  3001: {
+    message: "Invalid command provided",
+    description: "You must provide a valid command in the request body.",
+    category: "REQUEST_ERROR",
+    severity: "MEDIUM",
+  },
+  3002: {
+    message: "Server offline",
+    description:
+      "The server you are trying to reach is currently offline (has no players).",
+    category: "REQUEST_ERROR",
+    severity: "MEDIUM",
+  },
+
+  // Rate Limiting & Restrictions (4000-4999)
+  4001: {
+    message: "Rate limited",
+    description:
+      "You are being rate limited. Please reduce your request frequency and try again later.",
+    category: "RATE_LIMIT_ERROR",
+    severity: "MEDIUM",
+  },
+  4002: {
+    message: "Restricted command",
+    description:
+      "The command you are attempting to run is restricted and cannot be executed.",
+    category: "PERMISSION_ERROR",
+    severity: "MEDIUM",
+  },
+  4003: {
+    message: "Prohibited message",
+    description:
+      "The message you're trying to send contains prohibited content.",
+    category: "CONTENT_ERROR",
+    severity: "MEDIUM",
+  },
+
+  // Access Errors (9000-9999)
+  9998: {
+    message: "Restricted resource",
+    description: "The resource you are trying to access is restricted.",
+    category: "ACCESS_ERROR",
+    severity: "HIGH",
+  },
+  9999: {
+    message: "Outdated server module",
+    description:
+      "The module running on the in-game server is out of date. Please kick all players and try again.",
+    category: "VERSION_ERROR",
+    severity: "HIGH",
+  },
+};
+
+/**
+ * Gets error information by code
+ * @param {number} code - The ERLC error code
+ * @returns {Object} Error information object
+ */
+function getErrorInfo(code) {
+  const errorInfo = ERLC_ERROR_CODES[code];
+  if (!errorInfo) {
+    return {
+      message: `Unknown ERLC error code: ${code}`,
+      description:
+        "This error code is not recognized. Please check the ERLC API documentation.",
+      category: "UNKNOWN_ERROR",
+      severity: "MEDIUM",
+    };
+  }
+  return { ...errorInfo, code };
+}
+
+/**
+ * Checks if an error code indicates a retryable error
+ * @param {number} code - The ERLC error code
+ * @returns {boolean} True if the error might be resolved by retrying
+ */
+function isRetryableError(code) {
+  const retryableCodes = [1001, 1002, 4001]; // Communication errors and rate limits
+  return retryableCodes.includes(code);
+}
+
+/**
+ * Checks if an error code indicates an authentication issue
+ * @param {number} code - The ERLC error code
+ * @returns {boolean} True if the error is authentication-related
+ */
+function isAuthenticationError(code) {
+  return code >= 2000 && code <= 2999;
+}
+
+/**
+ * Gets suggested actions for an error code
+ * @param {number} code - The ERLC error code
+ * @returns {string[]} Array of suggested actions
+ */
+function getSuggestedActions(code) {
+  const actions = {
+    0: [
+      "Contact PRC support via API ticket",
+      "Check server logs for more details",
+    ],
+    1001: [
+      "Check server status",
+      "Verify server is online",
+      "Try again in a few minutes",
+    ],
+    1002: ["Try again later", "Contact PRC support if issue persists"],
+    2000: [
+      "Add server-key header to your request",
+      "Check API integration code",
+    ],
+    2001: [
+      "Verify server-key format",
+      "Get new server-key from server settings",
+    ],
+    2002: [
+      "Get new server-key from server settings",
+      "Verify server is still active",
+    ],
+    2003: [
+      "Check global API token configuration",
+      "Verify client initialization",
+    ],
+    2004: ["Contact PRC support immediately", "Review API usage policies"],
+    3001: ["Check command format", "Ensure command is not empty"],
+    3002: ["Wait for players to join server", "Check server status"],
+    4001: [
+      "Reduce request frequency",
+      "Implement rate limiting in your code",
+      "Wait before retrying",
+    ],
+    4002: ["Use a different command", "Check command permissions"],
+    4003: ["Review message content", "Remove prohibited words or phrases"],
+    9998: ["Check API permissions", "Contact server administrator"],
+    9999: [
+      "Kick all players from server",
+      "Restart server",
+      "Update server module",
+    ],
+  };
+
+  return (
+    actions[code] || [
+      "Check ERLC API documentation",
+      "Contact PRC support if needed",
+    ]
+  );
+}
+
+module.exports = {
+  ERLC_ERROR_CODES,
+  getErrorInfo,
+  isRetryableError,
+  isAuthenticationError,
+  getSuggestedActions,
+};

package/src/functions/assert.js

@@ -1,5 +1,5 @@
-module.exports = function(condition, message) {
-    if (!condition) {
-        throw new Error(message);
-    }
+module.exports = function(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
 }

package/src/functions/server/getBans.js

@@ -1,28 +1,53 @@
-const { BASEURL } = require("../../constants.js");
-
-module.exports = (serverToken) => {
-    return new Promise(async (resolve, reject) => {
-      try {
-        const fetch = await import("node-fetch");
-        const { config } = await import("../../erlc.js");
-  
-        const res = await fetch.default(`${BASEURL}/server/bans`, {
-          headers: {
-            "Authorization": config?.globalToken,
-            "Server-Key": serverToken,
-          },
-        });
-        const data = await res.json().catch((err) => {
-          return reject(err);
-        });
-  
-        if (!res.ok) {
-          return reject(data);
-        }
-  
-        resolve(data);
-      } catch (error) {
-        reject(error);
-      }
-    });
-  };
+const { BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
+
+/**
+ * Retrieves the list of banned players from a server
+ * @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");
+
+      // Check if global token is configured
+      if (!config?.globalToken) {
+        const error = await processError(
+          new Error(
+            "Global token not configured. Please initialize the client first."
+          )
+        );
+        return reject(error);
+      }
+
+      const res = await fetch.default(`${BASEURL}/server/bans`, {
+        headers: {
+          Authorization: config.globalToken,
+          "Server-Key": serverToken,
+        },
+        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);
+    }
+  });
+};