erlc-api 3.3.0 → 3.3.2-a

package/src/functions/server/requestServer.js

@@ -0,0 +1,179 @@
+const { BASEURL, LEGACY_BASEURL } = require("../../constants.js");
+const { processError } = require("../../utils/errorHandler.js");
+const cache = require("../../utils/cache.js");
+
+function assertServerToken(serverToken) {
+  if (!serverToken || typeof serverToken !== "string") {
+    throw new Error("Server token is required and must be a string");
+  }
+}
+
+function buildHeaders(serverToken, config, extraHeaders = {}) {
+  const headers = {
+    "Server-Key": serverToken,
+    ...extraHeaders,
+  };
+
+  if (config?.globalToken) {
+    headers["Authorization"] = config.globalToken;
+  }
+
+  return headers;
+}
+
+async function getFetch() {
+  const { config } = require("../../erlc.js");
+
+  if (config?.fetch) {
+    return {
+      fetch: config.fetch,
+      config,
+    };
+  }
+
+  if (typeof globalThis.fetch === "function") {
+    return {
+      fetch: globalThis.fetch,
+      config,
+    };
+  }
+
+  const fetch = await import("node-fetch");
+
+  return {
+    fetch: fetch.default,
+    config,
+  };
+}
+
+async function readError(res) {
+  return res.json().catch(() => ({ error: "Unknown API error" }));
+}
+
+function buildServerUrl(includes = []) {
+  const url = new URL(`${BASEURL}/server`);
+
+  for (const include of includes) {
+    url.searchParams.set(include, "true");
+  }
+
+  return url.toString();
+}
+
+async function requestJson(url, options) {
+  const res = await options.fetch(url, options.init);
+
+  if (!res.ok) {
+    const errorData = await readError(res);
+    throw await processError(res, errorData);
+  }
+
+  return res.json();
+}
+
+async function requestServer(serverToken, options = {}) {
+  assertServerToken(serverToken);
+
+  const {
+    endpoint = "server",
+    includes = [],
+    defaultValue = {},
+    transform = (data) => data,
+  } = options;
+
+  const { fetch, config } = await getFetch();
+  const useCache = !!config?.cache?.enabled;
+  const cacheExtras = includes.length ? includes.join(",") : "";
+  const key = cache.makeKey(endpoint, serverToken, cacheExtras);
+
+  if (useCache) {
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  const data = await requestJson(buildServerUrl(includes), {
+    fetch,
+    init: {
+      headers: buildHeaders(serverToken, config),
+      timeout: 10000,
+    },
+  });
+
+  const value = (await transform(data)) ?? defaultValue;
+
+  if (useCache) {
+    const ttlMs = cache.getTTL(endpoint, config);
+    cache.set(key, value, ttlMs);
+  }
+
+  return value;
+}
+
+async function requestApi(serverToken, path, options = {}) {
+  assertServerToken(serverToken);
+
+  const {
+    baseUrl = BASEURL,
+    method = "GET",
+    endpoint = path,
+    body,
+    defaultValue = {},
+    transform = (data) => data,
+    timeout = 10000,
+    useCache = true,
+  } = options;
+
+  const { fetch, config } = await getFetch();
+  const shouldCache = method === "GET" && useCache && !!config?.cache?.enabled;
+  const key = cache.makeKey(endpoint, serverToken);
+
+  if (shouldCache) {
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  const headers = buildHeaders(
+    serverToken,
+    config,
+    body ? { "Content-Type": "application/json" } : {},
+  );
+
+  const data = await requestJson(`${baseUrl}${path}`, {
+    fetch,
+    init: {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      timeout,
+    },
+  });
+
+  const value = (await transform(data)) ?? defaultValue;
+
+  if (shouldCache) {
+    const ttlMs = cache.getTTL(endpoint, config);
+    cache.set(key, value, ttlMs);
+  }
+
+  return value;
+}
+
+async function requestLegacyServer(serverToken, path, options = {}) {
+  return requestApi(serverToken, path, {
+    ...options,
+    baseUrl: LEGACY_BASEURL,
+  });
+}
+
+module.exports = {
+  assertServerToken,
+  buildHeaders,
+  getFetch,
+  requestServer,
+  requestApi,
+  requestLegacyServer,
+};

package/src/functions/server/runCommand.js

@@ -1,61 +1,30 @@
-const { BASEURL } = require("../../constants.js");
-const { processError } = require("../../utils/errorHandler.js");
+const { assertServerToken, requestApi } = require("./requestServer.js");
 
 /**
- * Executes a command on the server
+ * Executes a command on the server.
  * @param {string} serverToken - The server API key
  * @param {string} command - The command to execute
  * @returns {Promise<boolean>} Promise that resolves to true if command was executed successfully
  */
-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 (!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"));
-    }
-
-    try {
-      const fetch = await import("node-fetch");
-      const { config } = await import("../../erlc.js");
-
-      const requestBody = JSON.stringify({ command: command.trim() });
-
-      const headers = {
-        "Server-Key": serverToken,
-        "Content-Type": "application/json",
-      };
-      if (config?.globalToken) {
-        headers["Authorization"] = config.globalToken;
-      }
-
-      const res = await fetch.default(`${BASEURL}/server/command`, {
-        method: "POST",
-        headers: headers,
-        body: requestBody,
-        timeout: 15000, // 15 second timeout for commands
-      });
-
-      if (!res.ok) {
-        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) {
-      const processedError = await processError(error);
-      reject(processedError);
-    }
+module.exports = async (serverToken, command) => {
+  assertServerToken(serverToken);
+
+  if (!command || typeof command !== "string") {
+    throw new Error("Command is required and must be a string");
+  }
+
+  const trimmedCommand = command.trim();
+  if (trimmedCommand.length === 0) {
+    throw new Error("Command cannot be empty");
+  }
+
+  await requestApi(serverToken, "/server/command", {
+    method: "POST",
+    endpoint: "command",
+    body: { command: trimmedCommand },
+    timeout: 15000,
+    useCache: false,
   });
+
+  return true;
 };

package/src/types/index.d.ts

@@ -6,6 +6,9 @@ export class ErlcError extends Error {
   severity?: string;
   suggestions?: string[];
   retryable?: boolean;
+  retryAfter?: number;
+  bucket?: string;
+  commandId?: string;
   timestamp: string;
   originalError?: Error;
 
@@ -29,9 +32,23 @@ export interface ErrorInfo {
 
 export interface ClientConfig {
   globalToken?: string; // The ER:LC global API token
+  cache?: {
+    enabled?: boolean;
+    ttlMs?: Record<string, number>;
+    staleWhileRevalidate?: boolean;
+  };
+  logger?: {
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+  };
+  fetch?: (url: string, init?: any) => Promise<any>;
 }
 
-export const BASEURL = "https://api.policeroleplay.community/v1";
+export const API_ORIGIN = "https://api.erlc.gg";
+export const API_VERSION = "v2";
+export const BASEURL = "https://api.erlc.gg/v2";
+export const LEGACY_BASEURL = "https://api.erlc.gg/v1";
 
 type PlayerId = string;
 type PlayerName = string;
@@ -55,11 +72,30 @@ export interface ServerStatus {
   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
+  Players?: ServerPlayer[];
+  Staff?: ServerStaff;
+  JoinLogs?: JoinLog[];
+  Queue?: number[];
+  KillLogs?: KillLog[];
+  CommandLogs?: CommandLog[];
+  ModCalls?: ModcallLog[];
+  EmergencyCalls?: EmergencyCall[];
+  Vehicles?: VehiclesLog[];
 }
 
 export interface ServerPlayer {
   Player: ErlcPlayer;
+  Team?: string;
+  Callsign?: string | null;
+  Location?: {
+    LocationX?: number;
+    LocationZ?: number;
+    PostalCode?: string;
+    StreetName?: string;
+    BuildingNumber?: string;
+  };
   Permission: ErlcPlayerPermission;
+  WantedStars?: number;
 }
 
 export interface JoinLog {
@@ -91,13 +127,39 @@ export type ServerBan = Record<PlayerId, PlayerName>;
 export interface VehiclesLog {
   Texture: string | null;
   Name: string;
-  Owner: ErlcPlayer;
+  Owner: string;
+  Plate?: string;
+  ColorHex?: string;
+  ColorName?: string;
 }
 
 export interface ServerStaff {
-  CoOwners: number[];
   Admins: Record<string, string>;
   Mods: Record<string, string>;
+  Helpers?: Record<string, string>;
+}
+
+export interface EmergencyCall {
+  Team: string;
+  Caller: number;
+  Players: number[];
+  Position: [number, number];
+  StartedAt: number;
+  CallNumber: number;
+  Description: string;
+  PositionDescriptor: string;
+}
+
+export interface ServerIncludeOptions {
+  players?: boolean;
+  staff?: boolean;
+  joinLogs?: boolean;
+  queue?: boolean;
+  killLogs?: boolean;
+  commandLogs?: boolean;
+  modCalls?: boolean;
+  emergencyCalls?: boolean;
+  vehicles?: boolean;
 }
 
 export interface VSMCommandBody {
@@ -109,9 +171,13 @@ 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): Promise<ServerStatus>;
+export function getServer(
+  serverToken: string,
+  options?: ServerIncludeOptions,
+): Promise<ServerStatus>;
 export function getStaff(serverToken: string): Promise<ServerStaff>;
 export function getVehicles(serverToken: string): Promise<VehiclesLog[]>;
 export function runCommand(
@@ -122,6 +188,26 @@ export function runCommand(
 export function resetGlobalKey(): Promise<any>;
 
 export class Client {
-  constructor(options: ClientConfig);
+  constructor(options?: ClientConfig);
   config(): ClientConfig;
 }
+
+export const utils: {
+  cache: {
+    DEFAULT_TTLS: Record<string, number>;
+    makeKey: (endpoint: string, serverToken: string, extras?: string) => string;
+    getTTL: (endpoint: string, config: ClientConfig) => number;
+    get: (key: string) => any;
+    set: (key: string, value: any, ttlMs: number) => void;
+    invalidate: (key: string) => void;
+    invalidateByPrefix: (prefix: string) => void;
+  };
+  discord: {
+    formatServerStatus: (server: ServerStatus) => any;
+    formatPlayers: (players: ServerPlayer[]) => any;
+    formatKillLog: (log: KillLog) => any;
+    formatJoinLog: (log: JoinLog) => any;
+    formatCommandLog: (log: CommandLog) => any;
+    formatModCall: (log: ModcallLog) => any;
+  };
+};

package/src/utils/cache.js

@@ -0,0 +1,63 @@
+const DEFAULT_TTLS = {
+  server: 10000,
+  players: 3000,
+  vehicles: 5000,
+  joinlogs: 3000,
+  killlogs: 3000,
+  commandlogs: 3000,
+  modcalls: 3000,
+  emergencycalls: 3000,
+  staff: 10000,
+  queue: 2000,
+  bans: 10000,
+};
+
+const store = new Map();
+
+function now() {
+  return Date.now();
+}
+
+function makeKey(endpoint, serverToken, extras = "") {
+  return `${endpoint}:${serverToken}${extras ? `:${extras}` : ""}`;
+}
+
+function getTTL(endpoint, config) {
+  const ttlMap = config?.cache?.ttlMs || DEFAULT_TTLS;
+  const ttl = ttlMap[endpoint];
+  return typeof ttl === "number" && ttl > 0 ? ttl : 0;
+}
+
+function get(key) {
+  const entry = store.get(key);
+  if (!entry) return null;
+  if (entry.expiresAt && entry.expiresAt > now()) {
+    return entry.value;
+  }
+  return null;
+}
+
+function set(key, value, ttlMs) {
+  if (!ttlMs || ttlMs <= 0) return;
+  store.set(key, { value, expiresAt: now() + ttlMs });
+}
+
+function invalidate(key) {
+  store.delete(key);
+}
+
+function invalidateByPrefix(prefix) {
+  for (const k of store.keys()) {
+    if (k.startsWith(prefix)) store.delete(k);
+  }
+}
+
+module.exports = {
+  DEFAULT_TTLS,
+  makeKey,
+  getTTL,
+  get,
+  set,
+  invalidate,
+  invalidateByPrefix,
+};

package/src/utils/discord.js

@@ -0,0 +1,99 @@
+function formatServerStatus(server) {
+  return {
+    title: "Server Status",
+    color: 0x1f8b4c,
+    fields: [
+      { name: "Name", value: server.Name || "-", inline: true },
+      {
+        name: "Players",
+        value: `${server.CurrentPlayers}/${server.MaxPlayers}`,
+        inline: true,
+      },
+      { name: "Owner", value: server.OwnerUsername || "-", inline: true },
+      {
+        name: "Co-Owners",
+        value:
+          Array.isArray(server.CoOwnerUsernames) &&
+          server.CoOwnerUsernames.length
+            ? server.CoOwnerUsernames.join(", ")
+            : "None",
+        inline: false,
+      },
+      { name: "Join Key", value: server.JoinKey || "-", inline: true },
+      { name: "Vanity URL", value: server.VanityURL || "-", inline: false },
+    ],
+  };
+}
+
+function formatPlayers(players) {
+  const total = Array.isArray(players) ? players.length : 0;
+  const value =
+    total > 0
+      ? players
+          .slice(0, 10)
+          .map((p) => `• ${p.Player} (${p.Permission})`)
+          .join("\n")
+      : "No players online";
+  return {
+    title: `Players (${total})`,
+    color: 0x2f6fed,
+    description: value,
+  };
+}
+
+function formatKillLog(log) {
+  return {
+    title: "Kill Log",
+    color: 0xff5555,
+    fields: [
+      { name: "Killer", value: log.Killer || "-", inline: true },
+      { name: "Killed", value: log.Killed || "-", inline: true },
+      { name: "Timestamp", value: String(log.Timestamp || "-"), inline: true },
+    ],
+  };
+}
+
+function formatJoinLog(log) {
+  return {
+    title: log.Join ? "Player Joined" : "Player Left",
+    color: log.Join ? 0x50fa7b : 0xf1fa8c,
+    fields: [
+      { name: "Player", value: log.Player || "-", inline: true },
+      { name: "Timestamp", value: String(log.Timestamp || "-"), inline: true },
+    ],
+  };
+}
+
+function formatCommandLog(log) {
+  return {
+    title: "Command Executed",
+    color: 0xbd93f9,
+    fields: [
+      { name: "Player", value: log.Player || "-", inline: true },
+      { name: "Command", value: log.Command || "-", inline: false },
+      { name: "Timestamp", value: String(log.Timestamp || "-"), inline: true },
+    ],
+  };
+}
+
+function formatModCall(log) {
+  return {
+    title: "Mod Call",
+    color: 0x8be9fd,
+    fields: [
+      { name: "Caller", value: log.Caller || "-", inline: true },
+      { name: "Moderator", value: log.Moderator || "Unanswered", inline: true },
+      { name: "Timestamp", value: String(log.Timestamp || "-"), inline: true },
+    ],
+  };
+}
+
+module.exports = {
+  formatServerStatus,
+  formatPlayers,
+  formatKillLog,
+  formatJoinLog,
+  formatCommandLog,
+  formatModCall,
+};
+

package/src/utils/errorHandler.js

@@ -19,12 +19,24 @@ function handleApiError(response, errorData) {
     const errorInfo = getErrorInfo(errorData.code);
     const suggestions = getSuggestedActions(errorData.code);
 
-    const message = `${errorInfo.message}: ${errorInfo.description}`;
+    const apiMessage = errorData.message || errorData.error;
+    const message = apiMessage
+      ? `${errorInfo.message}: ${apiMessage}`
+      : `${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);
+    if (typeof errorData.retry_after === "number") {
+      error.retryAfter = errorData.retry_after;
+    }
+    if (errorData.bucket) {
+      error.bucket = errorData.bucket;
+    }
+    if (errorData.commandId) {
+      error.commandId = errorData.commandId;
+    }
 
     return error;
   }
@@ -80,6 +92,15 @@ function handleApiError(response, errorData) {
   error.category = "HTTP_ERROR";
   error.severity = status >= 500 ? "HIGH" : "MEDIUM";
   error.retryable = [429, 500, 502, 503].includes(status);
+  if (typeof errorData?.retry_after === "number") {
+    error.retryAfter = errorData.retry_after;
+  }
+  if (errorData?.bucket) {
+    error.bucket = errorData.bucket;
+  }
+  if (errorData?.commandId) {
+    error.commandId = errorData.commandId;
+  }
 
   return error;
 }

package/tests/cache.test.js

@@ -0,0 +1,46 @@
+const erlc = require("../src/erlc.js");
+const getPlayers = require("../src/functions/server/getPlayers.js");
+
+describe("Optional cache", () => {
+  const serverToken = "test-server";
+  let fetchCalls = 0;
+  let lastUrl = "";
+
+  const mockFetch = async (url, opts) => {
+    fetchCalls += 1;
+    lastUrl = url;
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({
+        Players: [{ Player: "User:123", Permission: "Normal" }],
+      }),
+    };
+  };
+
+  beforeEach(() => {
+    fetchCalls = 0;
+    lastUrl = "";
+    erlc.config.cache.enabled = false;
+    erlc.config.fetch = mockFetch;
+  });
+
+  test("Cache disabled by default (no cache hits)", async () => {
+    const res1 = await getPlayers(serverToken);
+    const res2 = await getPlayers(serverToken);
+    expect(Array.isArray(res1)).toBe(true);
+    expect(Array.isArray(res2)).toBe(true);
+    expect(lastUrl).toBe("https://api.erlc.gg/v2/server?Players=true");
+    expect(fetchCalls).toBe(2);
+  });
+
+  test("Cache enabled returns cached data on subsequent call", async () => {
+    erlc.config.cache.enabled = true;
+    erlc.config.cache.ttlMs.players = 5000;
+    const res1 = await getPlayers(serverToken);
+    const res2 = await getPlayers(serverToken);
+    expect(Array.isArray(res1)).toBe(true);
+    expect(Array.isArray(res2)).toBe(true);
+    expect(fetchCalls).toBe(1);
+  });
+});