erlc-v2 1.1.2 → 1.2.0

package/README.md

@@ -185,9 +185,13 @@ Core:
 
 Convenience methods:
 
-- `await client.players.list()`
-- `await client.map.render(options?)`
-- `await client.map.renderUser(userId, options?)`
+- `await client.players.list()`
+- `await client.players.get(userIdOrName)`
+- `await client.players.find(userIdOrName)`
+- `await client.players.findById(userId)`
+- `await client.players.findByName(username)`
+- `await client.map.render(options?)`
+- `await client.map.renderUser(userId, options?)`
 - `await client.staff.list()`
 - `await client.logs.kills()`
 - `await client.logs.joins()`
@@ -217,11 +221,35 @@ Convenience methods:
 
 - `bypassCache?: boolean`
 - `cacheTtlMs?: number`
-- `dedupe?: boolean`
-
-## Vehicle Search Helpers
-
-Find one exact plate:
+- `dedupe?: boolean`
+
+## Player Lookup
+
+`client.players.list()` returns the ER:LC player objects with the original API fields still on them. The wrapper also adds easier aliases like `userId`, `username`, `team`, `wantedStars`, and `location`.
+
+```js
+const player = await client.players.get(123456789);
+
+if (player?.location) {
+  console.log(player.username);
+  console.log(player.location.postalCode);
+  console.log(player.location.streetName);
+  console.log(player.location.buildingNumber);
+}
+```
+
+The original response is still there too:
+
+```js
+console.log(player.Player);
+console.log(player.Location?.PostalCode);
+```
+
+Player lookup uses the same cached `Players=true` server request as `players.list()`, so calling `get()`, `findById()`, or `findByName()` right after each other will not keep refetching from `erlc.gg` while the cache entry is still fresh.
+
+## Vehicle Search Helpers
+
+Find one exact plate:
 
 ```js
 const car = await client.vehicles.findByPlate("LINCOLN7");
@@ -333,9 +361,10 @@ Built-in routes:
 
 - `GET /erlc`
 - `GET /erlc/health`
-- `GET /erlc/server`
-- `GET /erlc/players`
-- `GET /erlc/vehicles`
+- `GET /erlc/server`
+- `GET /erlc/players`
+- `GET /erlc/players/:userIdOrName`
+- `GET /erlc/vehicles`
 - `GET /erlc/vehicles/:plate`
 - `GET /erlc/emergency-calls`
 - `POST /erlc/command`

package/index.d.ts

@@ -107,20 +107,54 @@ export interface CommandExecuteResult {
   };
 }
 
-export interface VehicleData {
-  Name?: string;
-  Owner?: string;
-  Plate?: string;
+export interface VehicleData {
+  Name?: string;
+  Owner?: string;
+  Plate?: string;
   Texture?: string | null;
   ColorHex?: string;
   ColorName?: string;
-  [key: string]: any;
-}
-
-export interface EmergencyCallData {
-  Team?: string;
-  Caller?: number;
-  Players?: number[];
+  [key: string]: any;
+}
+
+export interface PlayerLocationData {
+  LocationX?: number;
+  LocationZ?: number;
+  PostalCode?: string;
+  StreetName?: string;
+  BuildingNumber?: string;
+  locationX: number | null;
+  locationZ: number | null;
+  postalCode: string | null;
+  streetName: string | null;
+  buildingNumber: string | null;
+  raw: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface PlayerData {
+  Team?: string;
+  Player?: string;
+  Callsign?: string | null;
+  Location?: Record<string, any>;
+  Permission?: string;
+  WantedStars?: number;
+  name: string | null;
+  username: string | null;
+  userId: number | null;
+  team: string | null;
+  callsign: string | null;
+  permission: string | null;
+  wantedStars: number | null;
+  location: PlayerLocationData | null;
+  raw: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface EmergencyCallData {
+  Team?: string;
+  Caller?: number;
+  Players?: number[];
   Position?: number[];
   StartedAt?: number;
   CallNumber?: number;
@@ -220,10 +254,10 @@ export interface MapMarkerOptions {
   shadow?: boolean;
 }
 
-export interface MapRenderOptions {
-  userId?: number | string;
-  userIds?: Array<number | string>;
-  players?: any[];
+export interface MapRenderOptions {
+  userId?: number | string;
+  userIds?: Array<number | string>;
+  players?: PlayerData[] | any[];
   mapUrl?: string;
   season?: string;
   type?: string;
@@ -277,7 +311,7 @@ export interface ServerResponse {
   joinKey: string | null;
   accVerifiedReq: string | null;
   teamBalance: boolean | null;
-  players: any[];
+  players: PlayerData[];
   staff: any;
   joinLogs: any[];
   queue: any[];
@@ -339,9 +373,25 @@ export class Client extends EventEmitter {
       requestOptions?: RequestOptions,
     ) => Promise<ServerResponse>;
   };
-  players: {
-    list: (requestOptions?: RequestOptions) => Promise<any[]>;
-  };
+  players: {
+    list: (requestOptions?: RequestOptions) => Promise<PlayerData[]>;
+    get: (
+      user: number | string,
+      requestOptions?: RequestOptions,
+    ) => Promise<PlayerData | null>;
+    find: (
+      user: number | string,
+      requestOptions?: RequestOptions,
+    ) => Promise<PlayerData | null>;
+    findById: (
+      userId: number | string,
+      requestOptions?: RequestOptions,
+    ) => Promise<PlayerData | null>;
+    findByName: (
+      name: string,
+      requestOptions?: RequestOptions,
+    ) => Promise<PlayerData | null>;
+  };
   map: {
     render: (
       options?: MapRenderOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erlc-v2",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Premium, lightweight JavaScript wrapper for the ER:LC API v2.",
   "main": "index.js",
   "module": "index.mjs",

package/src/Client.js

@@ -5,11 +5,11 @@ const Poller = require("./events/Poller");
 const LocalApiServer = require("./api/LocalApiServer");
 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 { renderPlayerMap } = require("./map/renderPlayerMap");
-const { searchVehicles, findVehicleByPlate } = require("./util/vehicleSearch");
-const { ERLCError } = require("./errors");
+const { createLogger } = require("./util/logger");
+const { normalizeServerResponse } = require("./util/normalize");
+const { renderPlayerMap } = require("./map/renderPlayerMap");
+const { searchVehicles, findVehicleByPlate } = require("./util/vehicleSearch");
+const { ERLCError } = require("./errors");
 
 const BASE_URL = "https://api.erlc.gg";
 const BLOCKED_COMMANDS = new Set([
@@ -61,15 +61,42 @@ function getCommandKeyword(command) {
   return raw.split(/\s+/)[0].toLowerCase();
 }
 
-function isPromiseLike(value) {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    typeof value.then === "function"
-  );
-}
-
-class Client extends EventEmitter {
+function isPromiseLike(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof value.then === "function"
+  );
+}
+
+function low(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+function findPlayer(players, user, byName = false) {
+  if (!Array.isArray(players)) return null;
+
+  const text = low(user);
+  if (!text) return null;
+
+  const asId = Number(text);
+  const hasId = Number.isFinite(asId);
+
+  return (
+    players.find((p) => {
+      if (!p || typeof p !== "object") return false;
+      if (!byName && hasId && Number(p.userId) === asId) return true;
+
+      const name = low(p.username ?? p.name);
+      const raw = low(p.Player);
+      if (byName) return name === text || raw === text;
+
+      return name === text || raw === text;
+    }) ?? null
+  );
+}
+
+class Client extends EventEmitter {
   constructor(options = {}) {
     super();
 
@@ -104,12 +131,15 @@ class Client extends EventEmitter {
         this._fetchServer(flags, requestOptions),
     };
 
-    this.players = {
-      list: (requestOptions = {}) =>
-        this.server
-          .fetch({ players: true }, requestOptions)
-          .then((d) => d.players),
-    };
+    this.players = {
+      list: (requestOptions = {}) => this._listPlayers(requestOptions),
+      get: (user, requestOptions = {}) => this._getPlayer(user, requestOptions),
+      find: (user, requestOptions = {}) => this._getPlayer(user, requestOptions),
+      findById: (userId, requestOptions = {}) =>
+        this._getPlayer(userId, requestOptions),
+      findByName: (name, requestOptions = {}) =>
+        this._getPlayerByName(name, requestOptions),
+    };
 
     this.map = {
       render: (options = {}, requestOptions = {}) =>
@@ -340,7 +370,7 @@ class Client extends EventEmitter {
     return query;
   }
 
-  async _fetchServer(flags = {}, requestOptions = {}) {
+  async _fetchServer(flags = {}, requestOptions = {}) {
     if (this.state.disconnected && this.state.disconnectError) {
       throw this.state.disconnectError;
     }
@@ -365,10 +395,26 @@ class Client extends EventEmitter {
       bucket: response.bucket,
       rateLimit: response.rateLimit,
     };
-    return normalized;
-  }
-
-  async _executeCommand(command, requestOptions = {}) {
+    return normalized;
+  }
+
+  async _listPlayers(requestOptions = {}) {
+    return this.server
+      .fetch({ players: true }, requestOptions)
+      .then((d) => d.players);
+  }
+
+  async _getPlayer(user, requestOptions = {}) {
+    const players = await this._listPlayers(requestOptions);
+    return findPlayer(players, user);
+  }
+
+  async _getPlayerByName(name, requestOptions = {}) {
+    const players = await this._listPlayers(requestOptions);
+    return findPlayer(players, name, true);
+  }
+
+  async _executeCommand(command, requestOptions = {}) {
     if (this.state.disconnected && this.state.disconnectError) {
       throw this.state.disconnectError;
     }

package/src/api/LocalApiServer.js

@@ -249,10 +249,10 @@ class LocalApiServer {
         return;
       }
 
-      if (req.method === "GET" && routePath === "/players") {
-        const players = await this.client.players.list({
-          bypassCache: parseBool(url.searchParams.get("bypassCache")),
-        });
+      if (req.method === "GET" && routePath === "/players") {
+        const players = await this.client.players.list({
+          bypassCache: parseBool(url.searchParams.get("bypassCache")),
+        });
         this._recordRequest({
           req,
           url,
@@ -264,14 +264,43 @@ class LocalApiServer {
         sendJson(res, 200, {
           count: players.length,
           players,
-        });
-        return;
-      }
-
-      if (req.method === "GET" && routePath === "/vehicles") {
-        const vehicles = await this.client.vehicles.list({
-          bypassCache: parseBool(url.searchParams.get("bypassCache")),
-        });
+        });
+        return;
+      }
+
+      if (req.method === "GET" && routePath.startsWith("/players/")) {
+        const user = decodeURIComponent(routePath.slice("/players/".length));
+        const player = await this.client.players.get(user, {
+          bypassCache: parseBool(url.searchParams.get("bypassCache")),
+        });
+        if (!player) {
+          this._recordRequest({
+            req,
+            url,
+            startedAt,
+            kind: "route",
+            status: 404,
+            note: `player=${user}`,
+          });
+          sendJson(res, 404, { message: "Player not found" });
+          return;
+        }
+        this._recordRequest({
+          req,
+          url,
+          startedAt,
+          kind: "route",
+          status: 200,
+          note: `player=${user}`,
+        });
+        sendJson(res, 200, player);
+        return;
+      }
+
+      if (req.method === "GET" && routePath === "/vehicles") {
+        const vehicles = await this.client.vehicles.list({
+          bypassCache: parseBool(url.searchParams.get("bypassCache")),
+        });
         const filtered = searchVehicles(vehicles, {
           query: url.searchParams.get("query") || url.searchParams.get("search"),
           plate: url.searchParams.get("plate"),

package/src/util/normalize.js

@@ -1,3 +1,61 @@
+function toUserId(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "string") return null;
+
+  const text = value.trim();
+  if (!text) return null;
+
+  const idPart = text.includes(":") ? text.split(":").pop() : text;
+  const parsed = Number(idPart);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function playerName(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (!text) return null;
+  return text.includes(":") ? text.slice(0, text.lastIndexOf(":")) : text;
+}
+
+function normalizeLocation(raw) {
+  if (!raw || typeof raw !== "object") return null;
+
+  return {
+    ...raw,
+    locationX: raw.LocationX ?? null,
+    locationZ: raw.LocationZ ?? null,
+    postalCode: raw.PostalCode ?? null,
+    streetName: raw.StreetName ?? null,
+    buildingNumber: raw.BuildingNumber ?? null,
+    raw,
+  };
+}
+
+function normalizePlayer(p = {}) {
+  const rawPlayer = p.Player ?? p.Name ?? null;
+  const location = normalizeLocation(p.Location);
+
+  return {
+    ...p,
+    name: playerName(rawPlayer),
+    username: playerName(rawPlayer),
+    userId: toUserId(rawPlayer),
+    team: p.Team ?? null,
+    callsign: p.Callsign ?? null,
+    permission: p.Permission ?? null,
+    wantedStars: p.WantedStars ?? null,
+    location,
+    raw: p,
+  };
+}
+
+function normalizePlayers(rawPlayers) {
+  if (!Array.isArray(rawPlayers)) return [];
+  return rawPlayers.map((p) =>
+    p && typeof p === "object" ? normalizePlayer(p) : p,
+  );
+}
+
 function normalizeServerResponse(raw = {}) {
   return {
     name: raw.Name ?? null,
@@ -8,7 +66,7 @@ function normalizeServerResponse(raw = {}) {
     joinKey: raw.JoinKey ?? null,
     accVerifiedReq: raw.AccVerifiedReq ?? null,
     teamBalance: raw.TeamBalance ?? null,
-    players: Array.isArray(raw.Players) ? raw.Players : [],
+    players: normalizePlayers(raw.Players),
     staff: raw.Staff ?? { Admins: {}, Mods: {}, Helpers: {} },
     joinLogs: Array.isArray(raw.JoinLogs) ? raw.JoinLogs : [],
     queue: Array.isArray(raw.Queue) ? raw.Queue : [],
@@ -23,4 +81,7 @@ function normalizeServerResponse(raw = {}) {
 
 module.exports = {
   normalizeServerResponse,
+  normalizePlayer,
+  normalizePlayers,
+  toUserId,
 };