erlc-api 3.0.0 → 3.2.0

package/README.md

@@ -292,17 +292,37 @@ const handleApiCall = async () => {
     const result = await erlc.getServer(serverToken);
     return result;
   } catch (error) {
-    // Handle specific error types
-    if (error.status === 401) {
-      console.error("Authentication failed - check your tokens");
-    } else if (error.status === 404) {
-      console.error("Server not found - check your server token");
-    } else if (error.message.includes("Network error")) {
-      console.error("Connection issue - check your internet connection");
-    } else if (error.message.includes("timeout")) {
-      console.error("Request timed out - try again later");
-    } else {
-      console.error("Unexpected error:", error.message);
+    // The error is now an ErlcError with detailed information
+    console.error(`Error ${error.code}: ${error.message}`);
+    console.error(`Category: ${error.category}, Severity: ${error.severity}`);
+
+    // Handle specific ERLC error codes
+    switch (error.code) {
+      case 2002:
+        console.error(
+          "Invalid server key - get a new one from server settings"
+        );
+        break;
+      case 4001:
+        console.error("Rate limited - reduce request frequency");
+        break;
+      case 3002:
+        console.error("Server offline - wait for players to join");
+        break;
+      case 9999:
+        console.error("Server module outdated - restart server");
+        break;
+    }
+
+    // Show suggested actions
+    if (error.suggestions) {
+      console.error("Suggested actions:");
+      error.suggestions.forEach((action) => console.error(`- ${action}`));
+    }
+
+    // Check if error is retryable
+    if (error.retryable) {
+      console.error("This error might be resolved by retrying");
     }
 
     throw error; // Re-throw if needed
@@ -386,13 +406,62 @@ const joinLogs: JoinLog[] = await erlc.getJoinLogs(serverToken);
 
 ## 🐛 Error Types
 
-The wrapper provides detailed error information:
+The wrapper provides comprehensive error handling with specific ERLC error codes:
+
+### ERLC Error Codes
+
+| Code | Category             | Description                            |
+| ---- | -------------------- | -------------------------------------- |
+| 0    | System Error         | Unknown error occurred                 |
+| 1001 | Communication Error  | Error communicating with Roblox server |
+| 1002 | System Error         | Internal system error                  |
+| 2000 | Authentication Error | Missing server key                     |
+| 2001 | Authentication Error | Invalid server key format              |
+| 2002 | Authentication Error | Invalid or expired server key          |
+| 2003 | Authentication Error | Invalid global API key                 |
+| 2004 | Authentication Error | Server key banned                      |
+| 3001 | Request Error        | Invalid command provided               |
+| 3002 | Request Error        | Server offline (no players)            |
+| 4001 | Rate Limit Error     | Rate limited                           |
+| 4002 | Permission Error     | Restricted command                     |
+| 4003 | Content Error        | Prohibited message                     |
+| 9998 | Access Error         | Restricted resource                    |
+| 9999 | Version Error        | Outdated server module                 |
+
+### Error Properties
+
+All errors are instances of `ErlcError` with these properties:
+
+- `code`: ERLC error code or HTTP status
+- `message`: Human-readable error message
+- `category`: Error category (e.g., "AUTHENTICATION_ERROR")
+- `severity`: Error severity ("LOW", "MEDIUM", "HIGH", "CRITICAL")
+- `suggestions`: Array of suggested actions to resolve the error
+- `retryable`: Boolean indicating if the error might be resolved by retrying
+- `timestamp`: ISO timestamp when the error occurred
+
+### Retry Logic Example
 
-- **Network Errors**: Connection issues, DNS resolution failures
-- **Authentication Errors**: Invalid tokens, insufficient permissions
-- **API Errors**: Server-side errors with status codes and messages
-- **Validation Errors**: Invalid input parameters
-- **Timeout Errors**: Requests that take too long to complete
+```javascript
+async function withRetry(apiCall, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await apiCall();
+    } catch (error) {
+      if (!error.retryable || attempt === maxRetries) {
+        throw error;
+      }
+
+      // Wait before retrying with exponential backoff
+      const delay = 1000 * Math.pow(2, attempt - 1);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+// Usage
+const players = await withRetry(() => erlc.getPlayers(serverToken));
+```
 
 ## 🤝 Contributing
 

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,6 +1,6 @@
 {
   "name": "erlc-api",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "An ER:LC API wrapper for JS/TS",
   "main": "index.js",
   "types": "src/types/index.d.ts",

package/src/classes/client.js

@@ -1,5 +1,5 @@
-const erlc = require('../erlc.js')
-const assert = require('../functions/assert.js')
+const erlc = require("../erlc.js");
+const assert = require("../functions/assert.js");
 
 /**
  * @typedef {Object} ClientConfig
@@ -13,24 +13,27 @@ const assert = require('../functions/assert.js')
  */
 
 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 };
+    this.config();
+  }
 
-    /**
-     * @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
-    }
+  /**
+   * Updates and returns the client configurationg
+   * @returns {ClientConfig} The client configuration.
+   */
+  config() {
+    erlc.config = this.options;
+    return erlc.config;
+  }
 }
 
-module.exports = Client
+module.exports = Client;

package/src/erlc.js

@@ -11,5 +11,6 @@ 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.resetGlobalKey = require("./functions/global/resetGlobalKey.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/global/resetGlobalKey.js

@@ -0,0 +1,60 @@
+const { BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
+
+/**
+ * Resets the global API key
+ * @returns {Promise<string>} Promise that resolves to the new global API key
+ */
+module.exports = () => {
+  return new Promise(async (resolve, reject) => {
+    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}/api-key/reset`, {
+        method: "POST",
+        headers: {
+          Authorization: config.globalToken,
+        },
+        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);
+      }
+
+      // The response is likely a JSON with the new key, or just the key string?
+      // Docs say: "This will send a new key which can only be viewed once."
+      // Let's assume it returns a JSON object or just the string.
+      // Usually these APIs return a JSON object like { "key": "..." } or similar.
+      // 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);
+      reject(processedError);
+    }
+  });
+};