erlc-v2 1.0.0-beta.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 JavaScript client for the ER:LC API v2.
 
-Built for Node 18+ with no runtime dependencies.
+Built for Node 18+.
 
 ## Beta Notice
 
@@ -51,17 +51,17 @@ main()
   .finally(() => client.destroy());
 ```
 
-## Quick Start (ESM)
+## Quick Start (ESM)
 
 ```js
 import { Client } from "erlc-v2";
 
-const client = new Client({
-  serverKey: "YOUR_SERVER_KEY",
-});
-```
-
-## Options
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+});
+```
+
+## Options
 
 ```ts
 new Client({
@@ -73,13 +73,17 @@ new Client({
     enabled?: boolean, // default: true
     ttlMs?: number, // default: 1500
     maxSize?: number, // default: 500
+    provider?: "memory" | "redis", // default: auto (redis if redis config is present)
+    redisUrl?: string, // optional (requires `npm i redis`)
+    redisPrefix?: string, // default: "erlc-v2:cache"
+    redisClient?: object, // optional pre-configured Redis client
   },
   rateLimit?: {
     enabled?: boolean, // default: true
     strictSerial?: boolean, // default: true (global one-at-a-time queue)
-    perBucketConcurrency?: number, // default: 1
-    globalConcurrency?: number, // default: 1
-    unauthorizedThreshold?: number, // default: 3
+    bucketLimit?: number, // default: 1
+    totalLimit?: number, // default: 1
+    unauthLimit?: number, // default: 3
   },
   polling?: {
     enabled?: boolean, // default: true
@@ -89,6 +93,54 @@ new Client({
 });
 ```
 
+Legacy aliases (`perBucketConcurrency`, `globalConcurrency`, `unauthorizedThreshold`) are still accepted.
+
+## Redis Cache (Optional)
+
+You can use Redis instead of in-memory cache by passing either `cache.redisUrl` or `cache.redisClient`.
+
+If you use `redisUrl`, install the Redis client package:
+
+```bash
+npm i redis
+```
+
+Example with connection URL:
+
+```js
+const { Client } = require("erlc-v2");
+
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+  cache: {
+    provider: "redis",
+    redisUrl: "redis://localhost:6379",
+    redisPrefix: "myapp:erlc",
+    ttlMs: 2000,
+  },
+});
+```
+
+Example with your own Redis client instance:
+
+```js
+const { createClient } = require("redis");
+const { Client } = require("erlc-v2");
+
+(async () => {
+  const redis = createClient({ url: process.env.REDIS_URL });
+  await redis.connect();
+
+  const client = new Client({
+    serverKey: "YOUR_SERVER_KEY",
+    cache: {
+      redisClient: redis,
+      redisPrefix: "myapp:erlc",
+    },
+  });
+})();
+```
+
 ## API
 
 Core:
@@ -100,6 +152,8 @@ Core:
 Convenience methods:
 
 - `await client.players.list()`
+- `await client.map.render(options?)`
+- `await client.map.renderUser(userId, options?)`
 - `await client.staff.list()`
 - `await client.logs.kills()`
 - `await client.logs.joins()`
@@ -155,6 +209,87 @@ await client.commands.execute(":h Hey everyone!");
 await client.commands.execute(":log recentban He was trolling!");
 ```
 
+## Map Rendering
+
+Render an ER:LC map (`3121x3121`) with player markers that use Roblox avatars.
+
+```js
+const result = await client.map.render();
+
+// png buffer
+console.log(result.buffer);
+console.log(result.players.length);
+```
+
+`client.map.render()` renders the full map with all players currently in the server.
+
+Render an official season/type map preset:
+
+```js
+const fallBlank = await client.map.render({
+  season: "fall",
+  type: "blank",
+});
+
+const fallPostals = await client.map.render({
+  season: "fall",
+  type: "postals",
+});
+
+const winterBlank = await client.map.render({
+  season: "winter", // alias: "snow"
+  type: "blank",
+});
+
+const winterPostals = await client.map.render({
+  season: "winter",
+  type: "postals",
+});
+```
+
+Use your own map image URL:
+
+```js
+const customMap = await client.map.render({
+  mapUrl: "https://example.com/my-map.png", // mainly used in cases where we fail to add the most recent map when its released (sizing should be 3121x3121)
+});
+```
+
+Render only one player by Roblox user ID:
+
+```js
+const single = await client.map.renderUser(123456789, {
+  season: "winter",
+  type: "postals",
+});
+```
+
+Options:
+
+- `userId?: number | string`
+- `userIds?: Array<number | string>`
+- `players?: any[]` (use your own pre-fetched player payload)
+- `mapUrl?: string` (custom map URL; if set, this overrides `season`/`type`)
+- `season?: string` (`"fall"` or `"winter"`/`"snow"` for official presets)
+- `type?: string` (`"blank"` or `"postals"` for official presets)
+- `mapSeason?: string` (alias of `season`)
+- `mapType?: string` (alias of `type`)
+- `coordinateBounds?: { minX, maxX, minY, maxY, invertY? }`
+- `clampToMap?: boolean` (default: `true`)
+- `robloxHeadshotSize?: string` (default: `"150x150"`)
+- `marker?: { outerRadius, innerRadius, tipLength, tipWidth, fillColor, shadow }`
+
+Map size is fixed to `3121x3121`.
+
+Result shape:
+
+- `buffer` (`image/png`)
+- `map` (`{ url, season, type, width, height }`)
+- `players` (rendered marker metadata)
+- `skipped` (players skipped because coordinates were unavailable/invalid)
+- `requestedUserIds` (IDs requested via `userId` / `userIds`)
+- `unmatchedUserIds` (requested IDs not found in current player payload)
+
 ## Events
 
 - `ready`

package/index.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "events";
+import { Buffer } from "buffer";
 
 export interface LoggerLike {
   info?: (...args: any[]) => void;
@@ -11,11 +12,32 @@ export interface CacheOptions {
   enabled?: boolean;
   ttlMs?: number;
   maxSize?: number;
+  provider?: "memory" | "redis";
+  redisUrl?: string;
+  redisPrefix?: string;
+  redisClient?: {
+    get?: (key: string) => Promise<string | null> | string | null;
+    set?: (...args: any[]) => Promise<any> | any;
+    del?: (...args: any[]) => Promise<any> | any;
+    connect?: () => Promise<void> | void;
+    isOpen?: boolean;
+    status?: string;
+    sAdd?: (...args: any[]) => Promise<any> | any;
+    sadd?: (...args: any[]) => Promise<any> | any;
+    sRem?: (...args: any[]) => Promise<any> | any;
+    srem?: (...args: any[]) => Promise<any> | any;
+    sMembers?: (...args: any[]) => Promise<string[]> | string[];
+    smembers?: (...args: any[]) => Promise<string[]> | string[];
+    [key: string]: any;
+  };
 }
 
 export interface RateLimitOptions {
   enabled?: boolean;
   strictSerial?: boolean;
+  bucketLimit?: number;
+  totalLimit?: number;
+  unauthLimit?: number;
   perBucketConcurrency?: number;
   globalConcurrency?: number;
   unauthorizedThreshold?: number;
@@ -70,6 +92,71 @@ export interface CommandExecuteResult {
   };
 }
 
+export interface MapCoordinateBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+  invertY?: boolean;
+}
+
+export interface MapMarkerOptions {
+  outerRadius?: number;
+  innerRadius?: number;
+  tipLength?: number;
+  tipWidth?: number;
+  fillColor?: string;
+  shadow?: boolean;
+}
+
+export interface MapRenderOptions {
+  userId?: number | string;
+  userIds?: Array<number | string>;
+  players?: any[];
+  mapUrl?: string;
+  season?: string;
+  type?: string;
+  mapSeason?: string;
+  mapType?: string;
+  coordinateBounds?: MapCoordinateBounds;
+  clampToMap?: boolean;
+  robloxHeadshotSize?: string;
+  marker?: MapMarkerOptions;
+}
+
+export interface MapRenderedPlayer {
+  userId: number | null;
+  name: string | null;
+  avatarUrl: string | null;
+  sourceX: number;
+  sourceY: number;
+  sourceType: string;
+  pixelX: number;
+  pixelY: number;
+}
+
+export interface MapSkippedPlayer {
+  userId: number | null;
+  name: string | null;
+  reason: string;
+}
+
+export interface MapRenderResult {
+  buffer: Buffer;
+  mimeType: "image/png";
+  map: {
+    url: string;
+    season: string | null;
+    type: string | null;
+    width: number;
+    height: number;
+  };
+  players: MapRenderedPlayer[];
+  skipped: MapSkippedPlayer[];
+  requestedUserIds: number[];
+  unmatchedUserIds: number[];
+}
+
 export interface ServerResponse {
   name: string | null;
   ownerId: number | null;
@@ -130,7 +217,10 @@ export class ModuleOutOfDateError extends ERLCAPIError {}
 
 export class Client extends EventEmitter {
   constructor(options: ClientOptions);
-  cache: { clear: () => void };
+  cache: {
+    clear: () => void | Promise<void>;
+    destroy?: () => void | Promise<void>;
+  };
   server: {
     fetch: (
       flags?: ServerFetchFlags,
@@ -140,6 +230,17 @@ export class Client extends EventEmitter {
   players: {
     list: (requestOptions?: RequestOptions) => Promise<any[]>;
   };
+  map: {
+    render: (
+      options?: MapRenderOptions,
+      requestOptions?: RequestOptions,
+    ) => Promise<MapRenderResult>;
+    renderUser: (
+      userId: number | string,
+      options?: Omit<MapRenderOptions, "userId" | "userIds">,
+      requestOptions?: RequestOptions,
+    ) => Promise<MapRenderResult>;
+  };
   staff: {
     list: (requestOptions?: RequestOptions) => Promise<any>;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erlc-v2",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0",
   "description": "Premium, lightweight JavaScript wrapper for the ER:LC API v2.",
   "main": "index.js",
   "module": "index.mjs",
@@ -23,6 +23,12 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test:map": "node test-map-render.js"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.74"
+  },
   "keywords": [
     "erlc",
     "police-roleplay-community",

package/src/Client.js

@@ -6,6 +6,7 @@ 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 { ERLCError } = require("./errors");
 
 const BASE_URL = "https://api.policeroleplay.community";
@@ -54,6 +55,14 @@ 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 {
   constructor(options = {}) {
     super();
@@ -64,7 +73,7 @@ class Client extends EventEmitter {
     }
 
     this.logger = createLogger(this.options.logging, this.options.logger);
-    this.cache = new Cache(this.options.cache);
+    this.cache = new Cache(this.options.cache, this.logger);
 
     this.state = {
       disconnected: false,
@@ -96,6 +105,13 @@ class Client extends EventEmitter {
           .then((d) => d.players),
     };
 
+    this.map = {
+      render: (options = {}, requestOptions = {}) =>
+        this._renderMap(options, requestOptions),
+      renderUser: (userId, options = {}, requestOptions = {}) =>
+        this._renderMap({ ...options, userId }, requestOptions),
+    };
+
     this.staff = {
       list: (requestOptions = {}) =>
         this.server.fetch({ staff: true }, requestOptions).then((d) => d.staff),
@@ -333,6 +349,17 @@ class Client extends EventEmitter {
     });
   }
 
+  async _renderMap(options = {}, requestOptions = {}) {
+    if (this.state.disconnected && this.state.disconnectError) {
+      throw this.state.disconnectError;
+    }
+    if (this.state.destroyed) {
+      throw new ERLCError("Client has been destroyed");
+    }
+
+    return renderPlayerMap(this, options, requestOptions);
+  }
+
   _queueCommand(task) {
     const run = this.commandQueue.then(task, task);
     this.commandQueue = run.catch(() => {});
@@ -346,7 +373,34 @@ class Client extends EventEmitter {
     this.requestManager.destroy(
       this.state.disconnectError || new ERLCError("Client destroyed"),
     );
-    this.cache.clear();
+    const clearResult = this.cache.clear();
+    const maybeLog = (promiseLike, msg) => {
+      if (!isPromiseLike(promiseLike)) return;
+      promiseLike.catch((error) => {
+        this.logger.warn({
+          msg,
+          error: error?.message || String(error),
+        });
+      });
+    };
+
+    if (isPromiseLike(clearResult)) {
+      maybeLog(
+        clearResult
+          .catch((error) => {
+            this.logger.warn({
+              msg: "cache_clear_failed",
+              error: error?.message || String(error),
+            });
+          })
+          .finally(() => this.cache.destroy?.()),
+        "cache_destroy_failed",
+      );
+      return;
+    }
+
+    const destroyResult = this.cache.destroy?.();
+    maybeLog(destroyResult, "cache_destroy_failed");
   }
 }