erlc-api 3.0.0 → 3.2.0

package/src/functions/server/getVehicles.js

@@ -1,4 +1,5 @@
 const { BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
 
 /**
  * Retrieves server vehicles information
@@ -8,8 +9,8 @@ const { BASEURL } = require("../../constants.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'));
+    if (!serverToken || typeof serverToken !== "string") {
+      return reject(new Error("Server token is required and must be a string"));
     }
 
     try {
@@ -18,37 +19,35 @@ module.exports = (serverToken) => {
 
       // Check if global token is configured
       if (!config?.globalToken) {
-        return reject(new Error('Global token not configured. Please initialize the client first.'));
+        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/vehicles`, {
         headers: {
-          "Authorization": config.globalToken,
+          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 = new Error(`API Error: ${res.status} - ${errorData.error || res.statusText}`);
-        error.status = res.status;
-        error.data = errorData;
+        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) {
-      // Handle different types of errors
-      if (error.code === 'ENOTFOUND') {
-        reject(new Error('Network error: Unable to connect to ER:LC API'));
-      } else if (error.name === 'AbortError') {
-        reject(new Error('Request timeout: API took too long to respond'));
-      } else {
-        reject(error);
-      }
+      const processedError = await processError(error);
+      reject(processedError);
     }
   });
-};
+};

package/src/functions/server/runCommand.js

@@ -1,4 +1,5 @@
 const { BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
 
 /**
  * Executes a command on the server
@@ -9,16 +10,16 @@ const { BASEURL } = require("../../constants.js");
 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 (!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 || 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'));
+      return reject(new Error("Command cannot be empty"));
     }
 
     try {
@@ -27,7 +28,12 @@ module.exports = (serverToken, command) => {
 
       // Check if global token is configured
       if (!config?.globalToken) {
-        return reject(new Error('Global token not configured. Please initialize the client first.'));
+        const error = await processError(
+          new Error(
+            "Global token not configured. Please initialize the client first."
+          )
+        );
+        return reject(error);
       }
 
       const requestBody = JSON.stringify({ command: command.trim() });
@@ -35,7 +41,7 @@ module.exports = (serverToken, command) => {
       const res = await fetch.default(`${BASEURL}/server/command`, {
         method: "POST",
         headers: {
-          "Authorization": config.globalToken,
+          Authorization: config.globalToken,
           "Server-Key": serverToken,
           "Content-Type": "application/json",
         },
@@ -44,27 +50,18 @@ module.exports = (serverToken, command) => {
       });
 
       if (!res.ok) {
-        const errorData = await res.json().catch(() => ({ error: 'Unknown API error' }));
-        const error = new Error(`Command execution failed: ${res.status} - ${errorData.error || res.statusText}`);
-        error.status = res.status;
-        error.data = errorData;
+        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) {
-      // Handle different types of errors
-      if (error.code === 'ENOTFOUND') {
-        reject(new Error('Network error: Unable to connect to ER:LC API'));
-      } else if (error.name === 'AbortError') {
-        reject(new Error('Request timeout: Command took too long to execute'));
-      } else if (error.message.includes('JSON')) {
-        reject(new Error('Invalid command format'));
-      } else {
-        reject(error);
-      }
+      const processedError = await processError(error);
+      reject(processedError);
     }
   });
-};
+};

package/src/types/index.d.ts

@@ -1,98 +1,127 @@
-declare module "erlc-api" {
-  export interface ClientConfig {
-    globalToken: string; // The ER:LC global API token
-  }
-
-  export const BASEURL = "https://api.policeroleplay.community/v1";
-
-  type PlayerId = string;
-  type PlayerName = string;
-  type TextureName = string;
-  type CarName = string;
-
-  export type ErlcPlayer = `${PlayerName}:${PlayerId}`; // Playername:UserID
-  export type ErlcPlayerPermission =
-    | "Normal"
-    | "Server Administrator"
-    | "Server Owner"
-    | "Server Moderator";
-
-  export interface ServerStatus {
-    Name: string; // The server name
-    OwnerUsername: string; // The username of the server owner
-    CoOwnerUsernames: string[]; // The usernames of the server co owners
-    CurrentPlayers: number; // The amount of people currently in-game
-    MaxPlayers: number; // The amount of people who can join the server including server owner
-    JoinKey: string; // The code used to join the private server
-    AccVerifiedReq: "Disabled" | "Email" | "Phone/ID"; // The level of verification roblox accounts need to join the private server
-    TeamBalance: boolean; // If team balance is enabled or not
-    VanityURL: string; // The vanity URL to join the server
-  }
-
-  export interface ServerPlayer {
-    Player: ErlcPlayer;
-    Permission: ErlcPlayerPermission;
-  }
-
-  export interface JoinLog {
-    Join: boolean; // True is join and False is leave
-    Timestamp: number; // Timestamp in seconds
-    Player: ErlcPlayer;
-  }
-
-  export interface KillLog {
-    Killed: ErlcPlayer;
-    Timestamp: number; // Timestamp in seconds
-    Killer: ErlcPlayer;
-  }
-
-  export interface CommandLog {
-    Player: ErlcPlayer;
-    Timestamp: number; // Timestamp in seconds
-    Command: string;
-  }
-
-  export interface ModcallLog {
-    Caller: ErlcPlayer;
-    Moderator?: ErlcPlayer; // If call is unanswered property is undefined
-    Timestamp: number; // Timestamp in seconds
-  }
-
-  export type ServerBan = Record<PlayerId, PlayerName>;
-
-  export interface VehiclesLog {
-    Texture: string | null;
-    Name: string;
-    Owner: ErlcPlayer;
-  }
-
-  export interface ServerStaff {
-    CoOwners: number[];
-    Admins: Record<string, string>;
-    Mods: Record<string, string>;
-  }
-
-  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 getPlayers(serverToken: string): Promise<ServerPlayer[]>;
-  export function getQueue(serverToken: string): Promise<number[]>;
-  export function getServer(serverToken: string): 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 class Client {
-    constructor(options: ClientConfig);
-    config(): ClientConfig;
-  }
-}
+// Error handling types
+export class ErlcError extends Error {
+  code: string | number;
+  status?: number;
+  category?: string;
+  severity?: string;
+  suggestions?: string[];
+  retryable?: boolean;
+  timestamp: string;
+  originalError?: Error;
+
+  constructor(
+    message: string,
+    code: string | number,
+    status?: number,
+    originalError?: Error,
+  );
+  toJSON(): object;
+  toString(): string;
+}
+
+export interface ErrorInfo {
+  message: string;
+  description: string;
+  category: string;
+  severity: string;
+  code?: number;
+}
+
+export interface ClientConfig {
+  globalToken: string; // The ER:LC global API token
+}
+
+export const BASEURL = "https://api.policeroleplay.community/v1";
+
+type PlayerId = string;
+type PlayerName = string;
+type TextureName = string;
+type CarName = string;
+
+export type ErlcPlayer = `${PlayerName}:${PlayerId}`; // Playername:UserID
+export type ErlcPlayerPermission =
+  | "Normal"
+  | "Server Administrator"
+  | "Server Owner"
+  | "Server Moderator";
+
+export interface ServerStatus {
+  Name: string; // The server name
+  OwnerUsername: string; // The username of the server owner
+  CoOwnerUsernames: string[]; // The usernames of the server co owners
+  CurrentPlayers: number; // The amount of people currently in-game
+  MaxPlayers: number; // The amount of people who can join the server including server owner
+  JoinKey: string; // The code used to join the private server
+  AccVerifiedReq: "Disabled" | "Email" | "Phone/ID"; // The level of verification roblox accounts need to join the private server
+  TeamBalance: boolean; // If team balance is enabled or not
+  VanityURL: string; // The vanity URL to join the server
+}
+
+export interface ServerPlayer {
+  Player: ErlcPlayer;
+  Permission: ErlcPlayerPermission;
+}
+
+export interface JoinLog {
+  Join: boolean; // True is join and False is leave
+  Timestamp: number; // Timestamp in seconds
+  Player: ErlcPlayer;
+}
+
+export interface KillLog {
+  Killed: ErlcPlayer;
+  Timestamp: number; // Timestamp in seconds
+  Killer: ErlcPlayer;
+}
+
+export interface CommandLog {
+  Player: ErlcPlayer;
+  Timestamp: number; // Timestamp in seconds
+  Command: string;
+}
+
+export interface ModcallLog {
+  Caller: ErlcPlayer;
+  Moderator?: ErlcPlayer; // If call is unanswered property is undefined
+  Timestamp: number; // Timestamp in seconds
+}
+
+export type ServerBan = Record<PlayerId, PlayerName>;
+
+export interface VehiclesLog {
+  Texture: string | null;
+  Name: string;
+  Owner: ErlcPlayer;
+}
+
+export interface ServerStaff {
+  CoOwners: number[];
+  Admins: Record<string, string>;
+  Mods: Record<string, string>;
+}
+
+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 getPlayers(serverToken: string): Promise<ServerPlayer[]>;
+export function getQueue(serverToken: string): Promise<number[]>;
+export function getServer(serverToken: string): 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 resetGlobalKey(): Promise<any>;
+
+export class Client {
+  constructor(options: ClientConfig);
+  config(): ClientConfig;
+}

package/src/utils/errorHandler.js

@@ -0,0 +1,158 @@
+const ErlcError = require("../errors/ErlcError.js");
+const {
+  getErrorInfo,
+  getSuggestedActions,
+  isRetryableError,
+} = require("../errors/errorCodes.js");
+
+/**
+ * Handles API response errors and creates appropriate ErlcError instances
+ * @param {Response} response - The fetch response object
+ * @param {Object} errorData - The parsed error data from response
+ * @returns {ErlcError} Formatted ERLC error
+ */
+function handleApiError(response, errorData) {
+  const status = response.status;
+
+  // Check if error data contains ERLC error code
+  if (errorData && typeof errorData.code === "number") {
+    const errorInfo = getErrorInfo(errorData.code);
+    const suggestions = getSuggestedActions(errorData.code);
+
+    const message = `${errorInfo.message}: ${errorInfo.description}`;
+    const error = new ErlcError(message, errorData.code, status);
+    error.category = errorInfo.category;
+    error.severity = errorInfo.severity;
+    error.suggestions = suggestions;
+    error.retryable = isRetryableError(errorData.code);
+
+    return error;
+  }
+
+  // Handle HTTP status codes when no ERLC error code is provided
+  let message, code;
+
+  switch (status) {
+    case 400:
+      message = "Bad Request: The request was invalid or malformed";
+      code = "HTTP_400";
+      break;
+    case 401:
+      message = "Unauthorized: Authentication failed or missing credentials";
+      code = "HTTP_401";
+      break;
+    case 403:
+      message = "Forbidden: Access denied or insufficient permissions";
+      code = "HTTP_403";
+      break;
+    case 404:
+      message = "Not Found: The requested resource was not found";
+      code = "HTTP_404";
+      break;
+    case 422:
+      message = "Unprocessable Entity: The server has no players";
+      code = "HTTP_422";
+      break;
+    case 429:
+      message = "Too Many Requests: Rate limit exceeded";
+      code = "HTTP_429";
+      break;
+    case 500:
+      message = "Internal Server Error: Problem communicating with Roblox";
+      code = "HTTP_500";
+      break;
+    case 502:
+      message = "Bad Gateway: Server received invalid response";
+      code = "HTTP_502";
+      break;
+    case 503:
+      message = "Service Unavailable: Server temporarily unavailable";
+      code = "HTTP_503";
+      break;
+    default:
+      message = `HTTP Error ${status}: ${
+        errorData?.error || response.statusText || "Unknown error"
+      }`;
+      code = `HTTP_${status}`;
+  }
+
+  const error = new ErlcError(message, code, status);
+  error.category = "HTTP_ERROR";
+  error.severity = status >= 500 ? "HIGH" : "MEDIUM";
+  error.retryable = [429, 500, 502, 503].includes(status);
+
+  return error;
+}
+
+/**
+ * Handles network and other non-API errors
+ * @param {Error} originalError - The original error object
+ * @returns {ErlcError} Formatted ERLC error
+ */
+function handleNetworkError(originalError) {
+  let message, code, category;
+
+  if (originalError.code === "ENOTFOUND") {
+    message =
+      "Network Error: Unable to connect to ERLC API (DNS resolution failed)";
+    code = "NETWORK_DNS_ERROR";
+    category = "NETWORK_ERROR";
+  } else if (originalError.code === "ECONNREFUSED") {
+    message = "Network Error: Connection refused by ERLC API server";
+    code = "NETWORK_CONNECTION_REFUSED";
+    category = "NETWORK_ERROR";
+  } else if (
+    originalError.code === "ETIMEDOUT" ||
+    originalError.name === "AbortError"
+  ) {
+    message = "Request Timeout: API took too long to respond";
+    code = "REQUEST_TIMEOUT";
+    category = "TIMEOUT_ERROR";
+  } else if (originalError.message?.includes("JSON")) {
+    message = "Parse Error: Invalid JSON response from API";
+    code = "JSON_PARSE_ERROR";
+    category = "PARSE_ERROR";
+  } else {
+    message = `Unexpected Error: ${originalError.message}`;
+    code = "UNEXPECTED_ERROR";
+    category = "UNKNOWN_ERROR";
+  }
+
+  const error = new ErlcError(message, code, null, originalError);
+  error.category = category;
+  error.severity = "MEDIUM";
+  error.retryable = [
+    "NETWORK_DNS_ERROR",
+    "REQUEST_TIMEOUT",
+    "NETWORK_CONNECTION_REFUSED",
+  ].includes(code);
+
+  return error;
+}
+
+/**
+ * Main error handler that processes any error and returns a standardized ErlcError
+ * @param {Error|Response} error - The error to handle
+ * @param {Object} [errorData] - Additional error data if available
+ * @returns {ErlcError} Standardized ERLC error
+ */
+async function processError(error, errorData = null) {
+  // If it's already an ErlcError, return as-is
+  if (error instanceof ErlcError) {
+    return error;
+  }
+
+  // If it's a Response object (from fetch), handle as API error
+  if (error && typeof error.status === "number") {
+    return handleApiError(error, errorData);
+  }
+
+  // Handle as network/system error
+  return handleNetworkError(error);
+}
+
+module.exports = {
+  handleApiError,
+  handleNetworkError,
+  processError,
+};