erlc-v2 1.0.0-beta.0

package/src/Client.js

@@ -0,0 +1,353 @@
+const { EventEmitter } = require("events");
+const Cache = require("./cache/Cache");
+const RequestManager = require("./rest/RequestManager");
+const Poller = require("./events/Poller");
+const { DEFAULT_OPTIONS, QUERY_FLAG_MAP } = require("./util/constants");
+const { mergeOptions } = require("./util/options");
+const { createLogger } = require("./util/logger");
+const { normalizeServerResponse } = require("./util/normalize");
+const { ERLCError } = require("./errors");
+
+const BASE_URL = "https://api.policeroleplay.community";
+const BLOCKED_COMMANDS = new Set([
+  ":view",
+  ":to",
+  ":tocar",
+  ":toatv",
+  ":logs",
+  ":mods",
+  ":admins",
+  "helpers",
+  ":helpers",
+  ":administrators",
+  ":moderators",
+  ":killlogs",
+  ":kl",
+  ":cmds",
+  ":commands",
+]);
+const EVENT_ALIASES = {
+  onReady: "ready",
+  onJoin: "playerJoin",
+  onLeave: "playerLeave",
+  onKill: "kill",
+  onVehicleSpawn: "vehicleSpawn",
+  onVehicleDespawn: "vehicleDespawn",
+  onQueueUpdate: "queueUpdate",
+  onStaffUpdate: "staffUpdate",
+  onModCall: "modCall",
+  onCommandLog: "commandLog",
+  onLogCommand: "logCommand",
+  onServerUpdate: "serverUpdate",
+  onError: "error",
+  onDisconnect: "disconnect",
+};
+
+function resolveEventName(eventName) {
+  if (typeof eventName !== "string") return eventName;
+  return EVENT_ALIASES[eventName] || eventName;
+}
+
+function getCommandKeyword(command) {
+  const raw = String(command ?? "").trim();
+  if (!raw) return "";
+  return raw.split(/\s+/)[0].toLowerCase();
+}
+
+class Client extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    this.options = mergeOptions(DEFAULT_OPTIONS, options);
+    if (!this.options.serverKey || typeof this.options.serverKey !== "string") {
+      throw new ERLCError("Client requires a valid serverKey");
+    }
+
+    this.logger = createLogger(this.options.logging, this.options.logger);
+    this.cache = new Cache(this.options.cache);
+
+    this.state = {
+      disconnected: false,
+      destroyed: false,
+      disconnectReason: null,
+      disconnectError: null,
+    };
+    this.commandQueue = Promise.resolve();
+
+    this.requestManager = new RequestManager({
+      baseURL: BASE_URL,
+      serverKey: this.options.serverKey,
+      globalKey: this.options.globalKey,
+      cache: this.cache,
+      rateLimit: this.options.rateLimit,
+      logger: this.logger,
+      onDisconnect: (reason, error) => this._handleDisconnect(reason, error),
+    });
+
+    this.server = {
+      fetch: (flags = {}, requestOptions = {}) =>
+        this._fetchServer(flags, requestOptions),
+    };
+
+    this.players = {
+      list: (requestOptions = {}) =>
+        this.server
+          .fetch({ players: true }, requestOptions)
+          .then((d) => d.players),
+    };
+
+    this.staff = {
+      list: (requestOptions = {}) =>
+        this.server.fetch({ staff: true }, requestOptions).then((d) => d.staff),
+    };
+
+    this.logs = {
+      kills: (requestOptions = {}) =>
+        this.server
+          .fetch({ killLogs: true }, requestOptions)
+          .then((d) => d.killLogs),
+      joins: (requestOptions = {}) =>
+        this.server
+          .fetch({ joinLogs: true }, requestOptions)
+          .then((d) => d.joinLogs),
+      commands: (requestOptions = {}) =>
+        this.server
+          .fetch({ commandLogs: true }, requestOptions)
+          .then((d) => d.commandLogs),
+      modCalls: (requestOptions = {}) =>
+        this.server
+          .fetch({ modCalls: true }, requestOptions)
+          .then((d) => d.modCalls),
+    };
+
+    this.commands = {
+      execute: (command, requestOptions = {}) =>
+        this._executeCommand(command, requestOptions),
+    };
+
+    this.vehicles = {
+      list: (requestOptions = {}) =>
+        this.server
+          .fetch({ vehicles: true }, requestOptions)
+          .then((d) => d.vehicles),
+    };
+
+    this.queue = {
+      get: (requestOptions = {}) =>
+        this.server.fetch({ queue: true }, requestOptions).then((d) => d.queue),
+    };
+
+    this.poller = new Poller(this, this.options.polling);
+    if (this.options.polling?.enabled !== false) {
+      this.poller.start();
+    }
+  }
+
+  on(eventName, listener) {
+    return super.on(resolveEventName(eventName), listener);
+  }
+
+  once(eventName, listener) {
+    return super.once(resolveEventName(eventName), listener);
+  }
+
+  addListener(eventName, listener) {
+    return super.addListener(resolveEventName(eventName), listener);
+  }
+
+  prependListener(eventName, listener) {
+    return super.prependListener(resolveEventName(eventName), listener);
+  }
+
+  prependOnceListener(eventName, listener) {
+    return super.prependOnceListener(resolveEventName(eventName), listener);
+  }
+
+  off(eventName, listener) {
+    return super.off(resolveEventName(eventName), listener);
+  }
+
+  removeListener(eventName, listener) {
+    return super.removeListener(resolveEventName(eventName), listener);
+  }
+
+  onReady(listener) {
+    return this.on("ready", listener);
+  }
+
+  onJoin(listener) {
+    return this.on("playerJoin", listener);
+  }
+
+  onLeave(listener) {
+    return this.on("playerLeave", listener);
+  }
+
+  onKill(listener) {
+    return this.on("kill", listener);
+  }
+
+  onVehicleSpawn(listener) {
+    return this.on("vehicleSpawn", listener);
+  }
+
+  onVehicleDespawn(listener) {
+    return this.on("vehicleDespawn", listener);
+  }
+
+  onQueueUpdate(listener) {
+    return this.on("queueUpdate", listener);
+  }
+
+  onStaffUpdate(listener) {
+    return this.on("staffUpdate", listener);
+  }
+
+  onModCall(listener) {
+    return this.on("modCall", listener);
+  }
+
+  onCommandLog(listener) {
+    return this.on("commandLog", listener);
+  }
+
+  onLogCommand(listener) {
+    return this.on("logCommand", listener);
+  }
+
+  onServerUpdate(listener) {
+    return this.on("serverUpdate", listener);
+  }
+
+  onError(listener) {
+    return this.on("error", listener);
+  }
+
+  onDisconnect(listener) {
+    return this.on("disconnect", listener);
+  }
+
+  _handleDisconnect(reason, error) {
+    if (this.state.disconnected) return;
+    this.state.disconnected = true;
+    this.state.disconnectReason = reason;
+    this.state.disconnectError = error;
+
+    this.logger.warn({
+      msg: "client_disconnected",
+      reason,
+      error: error?.message,
+    });
+
+    this.poller.stop();
+    this.emit("disconnect", { reason, error });
+  }
+
+  _buildQueryFlags(flags) {
+    const query = {};
+    if (!flags || typeof flags !== "object") return query;
+
+    for (const [key, apiKey] of Object.entries(QUERY_FLAG_MAP)) {
+      if (flags[key] === true) {
+        query[apiKey] = true;
+      }
+    }
+
+    for (const apiKey of Object.values(QUERY_FLAG_MAP)) {
+      if (flags[apiKey] === true) {
+        query[apiKey] = true;
+      }
+    }
+
+    return query;
+  }
+
+  async _fetchServer(flags = {}, requestOptions = {}) {
+    if (this.state.disconnected && this.state.disconnectError) {
+      throw this.state.disconnectError;
+    }
+    if (this.state.destroyed) {
+      throw new ERLCError("Client has been destroyed");
+    }
+
+    const query = this._buildQueryFlags(flags);
+    const response = await this.requestManager.request({
+      method: "GET",
+      path: "/v2/server",
+      query,
+      useCache: requestOptions.bypassCache !== true,
+      cacheTtlMs: requestOptions.cacheTtlMs,
+      dedupe: requestOptions.dedupe !== false,
+    });
+
+    const normalized = normalizeServerResponse(response.data);
+    normalized.meta = {
+      status: response.status,
+      endpoint: response.endpoint,
+      bucket: response.bucket,
+      rateLimit: response.rateLimit,
+    };
+    return normalized;
+  }
+
+  async _executeCommand(command, requestOptions = {}) {
+    if (this.state.disconnected && this.state.disconnectError) {
+      throw this.state.disconnectError;
+    }
+    if (this.state.destroyed) {
+      throw new ERLCError("Client has been destroyed");
+    }
+    if (typeof command !== "string" || !command.trim()) {
+      throw new ERLCError("Command must be a non-empty string");
+    }
+
+    const normalizedCommand = command.trim();
+    const keyword = getCommandKeyword(normalizedCommand);
+    if (BLOCKED_COMMANDS.has(keyword)) {
+      throw new ERLCError(`Command "${keyword}" is blocked by client policy`);
+    }
+
+    return this._queueCommand(async () => {
+      if (this.state.disconnected && this.state.disconnectError) {
+        throw this.state.disconnectError;
+      }
+      if (this.state.destroyed) {
+        throw new ERLCError("Client has been destroyed");
+      }
+
+      const response = await this.requestManager.request({
+        method: "POST",
+        path: "/v1/server/command",
+        body: { command: normalizedCommand },
+        useCache: false,
+        dedupe: requestOptions.dedupe === true,
+      });
+
+      return {
+        ok: response.status >= 200 && response.status < 300,
+        status: response.status,
+        endpoint: response.endpoint,
+        bucket: response.bucket,
+        rateLimit: response.rateLimit,
+      };
+    });
+  }
+
+  _queueCommand(task) {
+    const run = this.commandQueue.then(task, task);
+    this.commandQueue = run.catch(() => {});
+    return run;
+  }
+
+  destroy() {
+    if (this.state.destroyed) return;
+    this.state.destroyed = true;
+    this.poller.destroy();
+    this.requestManager.destroy(
+      this.state.disconnectError || new ERLCError("Client destroyed"),
+    );
+    this.cache.clear();
+  }
+}
+
+module.exports = Client;

package/src/cache/Cache.js

@@ -0,0 +1,55 @@
+class Cache {
+  constructor(options = {}) {
+    this.enabled = options.enabled !== false;
+    this.ttlMs = typeof options.ttlMs === "number" ? options.ttlMs : 1500;
+    this.maxSize = typeof options.maxSize === "number" ? options.maxSize : 500;
+    this.store = new Map();
+  }
+
+  _isExpired(entry) {
+    return entry.expiresAt > 0 && entry.expiresAt <= Date.now();
+  }
+
+  _touch(key, entry) {
+    this.store.delete(key);
+    this.store.set(key, entry);
+  }
+
+  get(key) {
+    if (!this.enabled) return null;
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (this._isExpired(entry)) {
+      this.store.delete(key);
+      return null;
+    }
+    this._touch(key, entry);
+    return entry.value;
+  }
+
+  set(key, value, ttlMs) {
+    if (!this.enabled) return;
+    const effectiveTtl = typeof ttlMs === "number" ? ttlMs : this.ttlMs;
+    const entry = {
+      value,
+      expiresAt: effectiveTtl > 0 ? Date.now() + effectiveTtl : 0,
+    };
+    this.store.set(key, entry);
+    if (this.store.size > this.maxSize) {
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) {
+        this.store.delete(oldest);
+      }
+    }
+  }
+
+  delete(key) {
+    return this.store.delete(key);
+  }
+
+  clear() {
+    this.store.clear();
+  }
+}
+
+module.exports = Cache;

package/src/errors/ERLCAPIError.js

@@ -0,0 +1,11 @@
+const ERLCHttpError = require("./ERLCHttpError");
+
+class ERLCAPIError extends ERLCHttpError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.errorCode = options.errorCode ?? 0;
+    this.apiMessage = options.apiMessage ?? message;
+  }
+}
+
+module.exports = ERLCAPIError;

package/src/errors/ERLCError.js

@@ -0,0 +1,9 @@
+class ERLCError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.details = details;
+  }
+}
+
+module.exports = ERLCError;

package/src/errors/ERLCHttpError.js

@@ -0,0 +1,13 @@
+const ERLCError = require("./ERLCError");
+
+class ERLCHttpError extends ERLCError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.status = options.status ?? null;
+    this.endpoint = options.endpoint ?? null;
+    this.bucket = options.bucket ?? null;
+    this.body = options.body ?? null;
+  }
+}
+
+module.exports = ERLCHttpError;

package/src/errors/InvalidGlobalKeyError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class InvalidGlobalKeyError extends ERLCAPIError {}
+
+module.exports = InvalidGlobalKeyError;

package/src/errors/KeyBannedError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class KeyBannedError extends ERLCAPIError {}
+
+module.exports = KeyBannedError;

package/src/errors/KeyExpiredError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class KeyExpiredError extends ERLCAPIError {}
+
+module.exports = KeyExpiredError;

package/src/errors/ModuleOutOfDateError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class ModuleOutOfDateError extends ERLCAPIError {}
+
+module.exports = ModuleOutOfDateError;

package/src/errors/RateLimitError.js

@@ -0,0 +1,11 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class RateLimitError extends ERLCAPIError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.retryAfterMs = options.retryAfterMs ?? 0;
+    this.resetEpochMs = options.resetEpochMs ?? null;
+  }
+}
+
+module.exports = RateLimitError;

package/src/errors/RestrictedError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class RestrictedError extends ERLCAPIError {}
+
+module.exports = RestrictedError;

package/src/errors/ServerOfflineError.js

@@ -0,0 +1,5 @@
+const ERLCAPIError = require("./ERLCAPIError");
+
+class ServerOfflineError extends ERLCAPIError {}
+
+module.exports = ServerOfflineError;

package/src/errors/index.js

@@ -0,0 +1,12 @@
+module.exports = {
+  ERLCError: require("./ERLCError"),
+  ERLCHttpError: require("./ERLCHttpError"),
+  ERLCAPIError: require("./ERLCAPIError"),
+  RateLimitError: require("./RateLimitError"),
+  KeyExpiredError: require("./KeyExpiredError"),
+  KeyBannedError: require("./KeyBannedError"),
+  InvalidGlobalKeyError: require("./InvalidGlobalKeyError"),
+  ServerOfflineError: require("./ServerOfflineError"),
+  RestrictedError: require("./RestrictedError"),
+  ModuleOutOfDateError: require("./ModuleOutOfDateError"),
+};