erlc-v2 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,17 @@
+ERLC Wrapper Custom License
+Version 1.0
+Copyright (c) 2026
+
+Permission is granted to any person obtaining a copy of this software to:
+
+1. Use the software for any purpose.
+2. Modify the software for personal, internal, educational, or commercial use.
+3. Distribute compiled applications or systems that include modified or unmodified portions of this software, provided attribution is kept in documentation or notices.
+
+Restrictions:
+
+1. You may not claim authorship or original ownership of this software.
+2. You may not republish the original source code, in whole or substantial part, as your own package, template, or standalone repository.
+3. You may not remove this license text from original source files when redistributing source.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# erlc-v2
+
+JavaScript client for the ER:LC API v2.
+
+Built for Node 18+ with no runtime dependencies.
+
+## Beta Notice
+
+This wrapper is in beta (`1.0.0-beta.x`) and is not guaranteed to work 100% in all environments or API states.
+
+## Responsibility and API Safety
+
+You are responsible for how you use this wrapper and API key(s). If you use it recklessly (for example, aggressive request spam, ignoring rate limits, or abusive automation) and get rate-limited, blocked, or banned by PRC/Cloudflare, that is on you.
+
+This project is provided as-is. Always monitor your integration and respect PRC API rules and headers.
+
+## Install
+
+```bash
+npm install erlc-v2
+```
+
+## Quick Start (CommonJS)
+
+```js
+const { Client } = require("erlc-v2");
+
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+  // globalKey: "YOUR_GLOBAL_KEY", // optional
+});
+
+client.on("disconnect", ({ reason, error }) => {
+  console.error("Disconnected:", reason, error?.message);
+});
+
+async function main() {
+  const snapshot = await client.server.fetch({
+    players: true,
+    staff: true,
+    queue: true,
+  });
+
+  console.log("Server:", snapshot.name);
+  console.log("Players:", `${snapshot.currentPlayers}/${snapshot.maxPlayers}`);
+  console.log("Players payload:", snapshot.players.length);
+}
+
+main()
+  .catch(console.error)
+  .finally(() => client.destroy());
+```
+
+## Quick Start (ESM)
+
+```js
+import { Client } from "erlc-v2";
+
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+});
+```
+
+## Local System Test Script
+
+This repo includes a local test runner at `scripts/test-system.js`.
+
+1. Create `.env` in the project root:
+
+```env
+ERLC_SERVER_KEY=your_server_key
+# optional:
+# ERLC_GLOBAL_KEY=your_global_key
+```
+
+2. Run:
+
+```bash
+npm run test:system
+```
+
+What it does:
+
+- Fetches a full snapshot (`players`, `staff`, `joinLogs`, `queue`, `killLogs`, `commandLogs`, `modCalls`, `vehicles`)
+- Prints the full raw payload
+- Starts a live event monitor (`ready`, joins/leaves, kills, command logs, mod calls, queue/staff updates, disconnects, errors)
+- Prints internal request/rate-limit debug logs
+
+Useful flags:
+
+```bash
+# one snapshot, then exit
+npm run test:system -- --once
+
+# live monitor with custom poll interval (ms)
+npm run test:system -- --interval=3000
+
+# execute a v1 command, then keep monitoring events
+npm run test:system -- --command=":log recentban He was trolling!"
+```
+
+If your server is empty, seeing `CurrentPlayers: 0` and empty arrays is normal.
+
+## Options
+
+```ts
+new Client({
+  serverKey: string, // required
+  globalKey?: string, // optional
+  logging?: boolean, // default: false
+  logger?: { info, warn, error, debug },
+  cache?: {
+    enabled?: boolean, // default: true
+    ttlMs?: number, // default: 1500
+    maxSize?: number, // default: 500
+  },
+  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
+  },
+  polling?: {
+    enabled?: boolean, // default: true
+    intervalMs?: number, // default: 2500 (min enforced: 250)
+    bypassCache?: boolean, // default: true
+  },
+});
+```
+
+## API
+
+Core:
+
+- `await client.server.fetch(flags, requestOptions?)`
+- `client.destroy()`
+- `client.cache.clear()`
+
+Convenience methods:
+
+- `await client.players.list()`
+- `await client.staff.list()`
+- `await client.logs.kills()`
+- `await client.logs.joins()`
+- `await client.logs.commands()`
+- `await client.logs.modCalls()`
+- `await client.vehicles.list()`
+- `await client.queue.get()`
+- `await client.commands.execute(":h Hey everyone!")` (v1 endpoint)
+
+### Fetch Flags
+
+- `players` -> `Players`
+- `staff` -> `Staff`
+- `joinLogs` -> `JoinLogs`
+- `queue` -> `Queue`
+- `killLogs` -> `KillLogs`
+- `commandLogs` -> `CommandLogs`
+- `modCalls` -> `ModCalls`
+- `vehicles` -> `Vehicles`
+
+### Request Options
+
+- `bypassCache?: boolean`
+- `cacheTtlMs?: number`
+- `dedupe?: boolean`
+
+### Command Execution (v1)
+
+`client.commands.execute(command)` sends a POST request to `/v1/server/command`.
+Command execution is FIFO-queued client-side, so commands run one-at-a-time in order.
+
+Blocked by client policy (request will be rejected before hitting the API):
+
+- `:view`
+- `:to`
+- `:tocar`
+- `:toatv`
+- `:logs`
+- `:mods`
+- `:admins`
+- `helpers` / `:helpers`
+- `:administrators`
+- `:moderators`
+- `:killlogs`
+- `:kl`
+- `:cmds`
+- `:commands`
+
+Example:
+
+```js
+await client.commands.execute(":h Hey everyone!");
+await client.commands.execute(":log recentban He was trolling!");
+```
+
+## Events
+
+- `ready`
+- `playerJoin`
+- `playerLeave`
+- `kill`
+- `vehicleSpawn`
+- `vehicleDespawn`
+- `queueUpdate`
+- `staffUpdate`
+- `modCall`
+- `commandLog`
+- `logCommand` (only when command starts with `:log`)
+- `serverUpdate`
+- `error`
+- `disconnect` (`{ reason, error }`)
+
+Alias event names are also supported with `client.on(...)`:
+
+- `onReady`
+- `onJoin`
+- `onLeave`
+- `onKill`
+- `onVehicleSpawn`
+- `onVehicleDespawn`
+- `onQueueUpdate`
+- `onStaffUpdate`
+- `onModCall`
+- `onCommandLog`
+- `onLogCommand`
+- `onServerUpdate`
+- `onError`
+- `onDisconnect`
+
+Shortcut methods are available too:
+
+```js
+client.onJoin((payload) => console.log("join", payload));
+client.onLeave((payload) => console.log("leave", payload));
+client.onVehicleSpawn((payload) => console.log("spawn", payload));
+client.onLogCommand(({ command, parsed }) => {
+  console.log("raw command:", command.Command);
+  console.log("keyword:", parsed.keyword);
+  console.log("args:", parsed.args);
+});
+```
+
+`logCommand` / `onLogCommand` fires when a command starts with `:log`.
+
+Events are deduped per poll cycle so the same log entry is not emitted repeatedly.
+
+## Rate Limits
+
+Requests are automatically bucketed using API response headers:
+
+- `X-RateLimit-Bucket`
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+
+On `429`, the client blocks the affected bucket until retry time/reset.
+
+By default, requests are strictly serialized (`strictSerial: true`) so this client does not send parallel requests.
+This is intentionally conservative for anti-abuse/rate-limit safety.
+
+## Errors
+
+The client normalizes errors into classes:
+
+- `ERLCError`
+- `ERLCHttpError`
+- `ERLCAPIError`
+- `RateLimitError`
+- `KeyExpiredError` (`2002`)
+- `KeyBannedError` (`2004`)
+- `InvalidGlobalKeyError` (`2003`)
+- `ServerOfflineError` (`3002`)
+- `RestrictedError` (`9998`)
+- `ModuleOutOfDateError` (`9999`)
+
+Terminal key errors (`2002`, `2004`) trigger disconnect and stop polling.
+
+Repeated `403` responses can also trigger disconnect (reason: `"unauthorized"`).
+
+## Notes
+
+- API base URL: `https://api.policeroleplay.community`
+- `Server-Key` is required for requests
+- `Authorization` is optional (`globalKey`)

package/index.d.ts

@@ -0,0 +1,195 @@
+import { EventEmitter } from "events";
+
+export interface LoggerLike {
+  info?: (...args: any[]) => void;
+  warn?: (...args: any[]) => void;
+  error?: (...args: any[]) => void;
+  debug?: (...args: any[]) => void;
+}
+
+export interface CacheOptions {
+  enabled?: boolean;
+  ttlMs?: number;
+  maxSize?: number;
+}
+
+export interface RateLimitOptions {
+  enabled?: boolean;
+  strictSerial?: boolean;
+  perBucketConcurrency?: number;
+  globalConcurrency?: number;
+  unauthorizedThreshold?: number;
+}
+
+export interface PollingOptions {
+  enabled?: boolean;
+  intervalMs?: number;
+  bypassCache?: boolean;
+}
+
+export interface ClientOptions {
+  serverKey: string;
+  globalKey?: string;
+  logging?: boolean;
+  logger?: LoggerLike | null;
+  cache?: CacheOptions;
+  rateLimit?: RateLimitOptions;
+  polling?: PollingOptions;
+}
+
+export interface ServerFetchFlags {
+  players?: boolean;
+  staff?: boolean;
+  joinLogs?: boolean;
+  queue?: boolean;
+  killLogs?: boolean;
+  commandLogs?: boolean;
+  modCalls?: boolean;
+  vehicles?: boolean;
+}
+
+export interface RequestOptions {
+  bypassCache?: boolean;
+  cacheTtlMs?: number;
+  dedupe?: boolean;
+}
+
+export interface CommandRequestOptions {
+  dedupe?: boolean;
+}
+
+export interface CommandExecuteResult {
+  ok: boolean;
+  status: number;
+  endpoint: string;
+  bucket: string;
+  rateLimit: {
+    limit: number;
+    remaining: number;
+    resetEpochMs: number | null;
+  };
+}
+
+export interface ServerResponse {
+  name: string | null;
+  ownerId: number | null;
+  coOwnerIds: number[];
+  currentPlayers: number;
+  maxPlayers: number;
+  joinKey: string | null;
+  accVerifiedReq: string | null;
+  teamBalance: boolean | null;
+  players: any[];
+  staff: any;
+  joinLogs: any[];
+  queue: any[];
+  killLogs: any[];
+  commandLogs: any[];
+  modCalls: any[];
+  vehicles: any[];
+  raw: Record<string, any>;
+  meta: {
+    status: number;
+    endpoint: string;
+    bucket: string;
+    rateLimit: {
+      limit: number;
+      remaining: number;
+      resetEpochMs: number | null;
+    };
+  };
+}
+
+export class ERLCError extends Error {
+  details: Record<string, any>;
+}
+
+export class ERLCHttpError extends ERLCError {
+  status: number | null;
+  endpoint: string | null;
+  bucket: string | null;
+  body: any;
+}
+
+export class ERLCAPIError extends ERLCHttpError {
+  errorCode: number;
+  apiMessage: string;
+}
+
+export class RateLimitError extends ERLCAPIError {
+  retryAfterMs: number;
+  resetEpochMs: number | null;
+}
+
+export class KeyExpiredError extends ERLCAPIError {}
+export class KeyBannedError extends ERLCAPIError {}
+export class InvalidGlobalKeyError extends ERLCAPIError {}
+export class ServerOfflineError extends ERLCAPIError {}
+export class RestrictedError extends ERLCAPIError {}
+export class ModuleOutOfDateError extends ERLCAPIError {}
+
+export class Client extends EventEmitter {
+  constructor(options: ClientOptions);
+  cache: { clear: () => void };
+  server: {
+    fetch: (
+      flags?: ServerFetchFlags,
+      requestOptions?: RequestOptions,
+    ) => Promise<ServerResponse>;
+  };
+  players: {
+    list: (requestOptions?: RequestOptions) => Promise<any[]>;
+  };
+  staff: {
+    list: (requestOptions?: RequestOptions) => Promise<any>;
+  };
+  logs: {
+    kills: (requestOptions?: RequestOptions) => Promise<any[]>;
+    joins: (requestOptions?: RequestOptions) => Promise<any[]>;
+    commands: (requestOptions?: RequestOptions) => Promise<any[]>;
+    modCalls: (requestOptions?: RequestOptions) => Promise<any[]>;
+  };
+  commands: {
+    execute: (
+      command: string,
+      requestOptions?: CommandRequestOptions,
+    ) => Promise<CommandExecuteResult>;
+  };
+  vehicles: {
+    list: (requestOptions?: RequestOptions) => Promise<any[]>;
+  };
+  queue: {
+    get: (requestOptions?: RequestOptions) => Promise<any[]>;
+  };
+  onReady(listener: (...args: any[]) => void): this;
+  onJoin(listener: (...args: any[]) => void): this;
+  onLeave(listener: (...args: any[]) => void): this;
+  onKill(listener: (...args: any[]) => void): this;
+  onVehicleSpawn(listener: (...args: any[]) => void): this;
+  onVehicleDespawn(listener: (...args: any[]) => void): this;
+  onQueueUpdate(listener: (...args: any[]) => void): this;
+  onStaffUpdate(listener: (...args: any[]) => void): this;
+  onModCall(listener: (...args: any[]) => void): this;
+  onCommandLog(listener: (...args: any[]) => void): this;
+  onLogCommand(listener: (...args: any[]) => void): this;
+  onServerUpdate(listener: (...args: any[]) => void): this;
+  onError(listener: (...args: any[]) => void): this;
+  onDisconnect(listener: (...args: any[]) => void): this;
+  destroy(): void;
+}
+
+declare const _default: {
+  Client: typeof Client;
+  ERLCError: typeof ERLCError;
+  ERLCHttpError: typeof ERLCHttpError;
+  ERLCAPIError: typeof ERLCAPIError;
+  RateLimitError: typeof RateLimitError;
+  KeyExpiredError: typeof KeyExpiredError;
+  KeyBannedError: typeof KeyBannedError;
+  InvalidGlobalKeyError: typeof InvalidGlobalKeyError;
+  ServerOfflineError: typeof ServerOfflineError;
+  RestrictedError: typeof RestrictedError;
+  ModuleOutOfDateError: typeof ModuleOutOfDateError;
+};
+
+export default _default;

package/index.js

@@ -0,0 +1 @@
+module.exports = require("./src");

package/index.mjs

@@ -0,0 +1,14 @@
+import cjs from "./index.js";
+
+export const Client = cjs.Client;
+export const ERLCError = cjs.ERLCError;
+export const ERLCHttpError = cjs.ERLCHttpError;
+export const ERLCAPIError = cjs.ERLCAPIError;
+export const RateLimitError = cjs.RateLimitError;
+export const KeyExpiredError = cjs.KeyExpiredError;
+export const KeyBannedError = cjs.KeyBannedError;
+export const InvalidGlobalKeyError = cjs.InvalidGlobalKeyError;
+export const ServerOfflineError = cjs.ServerOfflineError;
+export const RestrictedError = cjs.RestrictedError;
+export const ModuleOutOfDateError = cjs.ModuleOutOfDateError;
+export default cjs;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "erlc-v2",
+  "version": "1.0.0-beta.0",
+  "description": "Premium, lightweight JavaScript wrapper for the ER:LC API v2.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "erlc",
+    "police-roleplay-community",
+    "api",
+    "wrapper",
+    "nodejs"
+  ],
+  "license": "LicenseRef-ERLC-Custom",
+  "author": "",
+  "type": "commonjs"
+}