erlc-api 3.3.1 → 3.3.2-a

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);
+  });
+});