erlc-v2 1.0.0 → 1.1.0

package/README.md

@@ -1,381 +1,609 @@
-# erlc-v2
-
-JavaScript client for the ER:LC API v2.
-
-Built for Node 18+.
-
-## 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",
-});
-```
-
-## 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
-    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)
-    bucketLimit?: number, // default: 1
-    totalLimit?: number, // default: 1
-    unauthLimit?: number, // default: 3
-  },
-  polling?: {
-    enabled?: boolean, // default: true
-    intervalMs?: number, // default: 2500 (min enforced: 250)
-    bypassCache?: boolean, // default: true
-  },
-});
-```
-
-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:
-
-- `await client.server.fetch(flags, requestOptions?)`
-- `client.destroy()`
-- `client.cache.clear()`
-
-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()`
-- `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!");
-```
-
-## 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`
-- `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
+# erlc-v2
+
+JavaScript client for the ER:LC API v2.
+
+Built for Node 18+.
+
+Quick note: sorry this update took a while. There is a lot in this version, and I did not have a ton of time to get to it, so it ended up taking longer than I wanted.
+
+## New Features
+
+- `client.commands.execute()` now uses `/v2/server/command`
+- emergency calls are supported
+- vehicle lookup helpers are built in
+- you can start a small local API with `api: { port: 3001 }`
+- event webhooks are supported and signature-checked before they fire events
+
+## Stable Release
+
+This wrapper is on a stable release track (`1.0.0+`).
+
+## Responsibility and API Safety
+
+Use your keys like a normal person. If you spam requests, ignore rate limits, or build dumb abuse tools and PRC or Cloudflare blocks you, that is on you.
+
+This project is provided as-is. Keep an eye on your own integration and follow the PRC API rules.
+
+## Install
+
+```bash
+npm install erlc-v2
+```
+
+## Quick Start (CommonJS)
+
+```js
+const { Client } = require("erlc-v2");
+
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+  polling: {
+    enabled: true,
+  },
+});
+
+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,
+    vehicles: true,
+    emergencyCalls: true,
+  });
+
+  console.log("Server:", snapshot.name);
+  console.log("Players:", `${snapshot.currentPlayers}/${snapshot.maxPlayers}`);
+  console.log("Vehicles:", snapshot.vehicles.length);
+  console.log("Emergency calls:", snapshot.emergencyCalls.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",
+});
+```
+
+## 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
+    provider?: "memory" | "redis", // default: auto
+    redisUrl?: string,
+    redisPrefix?: string, // default: "erlc-v2:cache"
+    redisClient?: object,
+  },
+  rateLimit?: {
+    enabled?: boolean, // default: true
+    strictSerial?: boolean, // default: true
+    bucketLimit?: number, // default: 1
+    totalLimit?: number, // default: 1
+    unauthLimit?: number, // default: 3
+  },
+  polling?: {
+    enabled?: boolean, // default: true
+    intervalMs?: number, // default: 2500
+    bypassCache?: boolean, // default: true
+  },
+  api?: {
+    enabled?: boolean, // default: false unless port is set
+    host?: string, // default: "127.0.0.1"
+    port?: number, // required if you want the local API server
+    path?: string, // default: "/erlc"
+    webhookPath?: string, // default: `${path}/events`
+    publicUrl?: string, // optional, used to build webhookUrl in client.api.info()
+    token?: string, // optional bearer token for built-in routes
+    logRequests?: boolean, // default: true, logs route/webhook hits to the console
+  },
+});
+```
+
+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:
+
+- `await client.server.fetch(flags, requestOptions?)`
+- `await client.commands.execute(command)`
+- `client.destroy()`
+- `client.cache.clear()`
+
+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()`
+- `await client.logs.commands()`
+- `await client.logs.modCalls()`
+- `await client.logs.emergencyCalls()`
+- `await client.vehicles.list()`
+- `await client.vehicles.search(filters)`
+- `await client.vehicles.findByPlate(plate)`
+- `await client.vehicles.findByOwner(owner)`
+- `await client.vehicles.findOne(filters)`
+- `await client.queue.get()`
+
+### Fetch Flags
+
+- `players` -> `Players`
+- `staff` -> `Staff`
+- `joinLogs` -> `JoinLogs`
+- `queue` -> `Queue`
+- `killLogs` -> `KillLogs`
+- `commandLogs` -> `CommandLogs`
+- `modCalls` -> `ModCalls`
+- `emergencyCalls` -> `EmergencyCalls`
+- `vehicles` -> `Vehicles`
+
+### Request Options
+
+- `bypassCache?: boolean`
+- `cacheTtlMs?: number`
+- `dedupe?: boolean`
+
+## Vehicle Search Helpers
+
+Find one exact plate:
+
+```js
+const car = await client.vehicles.findByPlate("LINCOLN7");
+
+if (car) {
+  console.log(car.Owner, car.Name, car.Plate);
+}
+```
+
+Search across plate, owner, name, color, and texture:
+
+```js
+const matches = await client.vehicles.search({
+  query: "lincoln",
+});
+
+const ownerCars = await client.vehicles.findByOwner("lando");
+
+const blackTahoes = await client.vehicles.search({
+  name: "tahoe",
+  color: "black",
+});
+```
+
+Exact matching is supported too:
+
+```js
+const exact = await client.vehicles.findOne({
+  plate: "A12BCD",
+  owner: "SomePlayer",
+  exact: true,
+});
+```
+
+## Emergency Calls
+
+```js
+const calls = await client.logs.emergencyCalls();
+
+for (const call of calls) {
+  console.log(call.CallNumber, call.Team, call.Description);
+}
+
+client.on("emergencyCall", ({ emergencyCall }) => {
+  console.log("New emergency call:", emergencyCall.Description);
+});
+```
+
+## Command Execution
+
+`client.commands.execute(command)` sends a POST request to `/v2/server/command`.
+Command execution is FIFO-queued client-side, so commands run one-at-a-time in order.
+
+Blocked by client policy:
+
+- `:view`
+- `:to`
+- `:tocar`
+- `:toatv`
+- `:logs`
+- `:mods`
+- `:admins`
+- `helpers` / `:helpers`
+- `:administrators`
+- `:moderators`
+- `:killlogs`
+- `:kl`
+- `:cmds`
+- `:commands`
+
+Example:
+
+```js
+const result = await client.commands.execute(":h Hey everyone!");
+console.log(result.message);
+```
+
+## Built-in Local API Server
+
+If you want the wrapper to expose a small HTTP server, it can do that too.
+
+```js
+const client = new Client({
+  serverKey: process.env.ERLC_SERVER_KEY,
+  api: {
+    port: 3001,
+    host: "127.0.0.1",
+    path: "/erlc",
+    publicUrl: "https://hooks.example.com",
+    token: process.env.ERLC_LOCAL_API_TOKEN,
+  },
+});
+
+client.api.info();
+```
+
+If `api.port` is set, the local API auto-starts with the client. You can also call `await client.api.start()` yourself.
+
+By default it logs incoming route hits and verified webhook payloads to the console.
+
+If you want to react to ER:LC webhooks in your own code, use:
+
+- `client.onWebhook(...)`
+- `client.onWebhookCommand(...)`
+- `client.onWebhookEmergencyCall(...)`
+
+Those only fire after the webhook signature checks out.
+
+Built-in routes:
+
+- `GET /erlc`
+- `GET /erlc/health`
+- `GET /erlc/server`
+- `GET /erlc/players`
+- `GET /erlc/vehicles`
+- `GET /erlc/vehicles/:plate`
+- `GET /erlc/emergency-calls`
+- `POST /erlc/command`
+- `POST /erlc/events`
+
+`/erlc/vehicles` accepts query params like `search`, `plate`, `owner`, `name`, `color`, `texture`, `exact`, and `limit`.
+
+If you set `api.token`, send either:
+
+- `Authorization: Bearer YOUR_TOKEN`
+- `X-API-Token: YOUR_TOKEN`
+
+## Event Webhook Support
+
+The built-in API can take ER:LC event webhooks and verify the signatures for you.
+
+```js
+const client = new Client({
+  serverKey: process.env.ERLC_SERVER_KEY,
+  api: {
+    port: 3001,
+    publicUrl: "https://hooks.example.com",
+  },
+});
+
+client.onWebhook((payload) => {
+  console.log("Webhook type:", payload.type);
+  console.log("Event name:", payload.event);
+});
+
+client.onWebhookCommand((payload) => {
+  console.log("Command:", payload.command);
+  console.log("Args:", payload.args);
+  console.log("Origin:", payload.origin);
+  // react to in-game ; commands here
+});
+
+client.onWebhookEmergencyCall((payload) => {
+  console.log("Event:", payload.event);
+  console.log("Origin:", payload.origin);
+  console.log("Data:", payload.data);
+  // react to emergency calls here
+});
+```
+
+Useful flattened webhook fields:
+
+- `payload.type`
+- `payload.event`
+- `payload.origin`
+- `payload.server`
+- `payload.eventTimestamp`
+- `payload.data`
+- `payload.command`
+- `payload.args`
+- `payload.argument`
+- `payload.entry`
+- `payload.events`
+
+For in-game custom commands, `onWebhookCommand(...)` is usually the one you want. Most of the time `payload.command`, `payload.args`, and `payload.origin` are enough.
+
+If your public URL is `https://hooks.example.com` and your API path is the default, set this in your ER:LC server settings:
+
+```txt
+https://hooks.example.com/erlc/events
+```
+
+If you want the longer request shape with type information, use:
+
+```txt
+https://hooks.example.com/erlc/events?long=true
+```
+
+## Domain, Hosting, and Reverse Proxy Notes
+
+The event webhook has to hit a public HTTPS URL. A local port by itself is not enough.
+
+Important:
+
+- Most Discord bot hosts are bad for this because they do not let you expose your own API cleanly.
+- If your host does not allow inbound HTTP traffic, PRC will never reach your webhook.
+- You need something public in front of your wrapper.
+
+Common setups:
+
+- Buy a domain and point it at a VPS.
+- Run the wrapper on a VPS and put NGINX or Caddy in front of it.
+- Run it somewhere private and use Cloudflare Tunnel.
+
+Common places people use for domains:
+
+- Cloudflare Registrar: `https://www.cloudflare.com/products/registrar/`
+- Namecheap: `https://www.namecheap.com/`
+- Porkbun: `https://porkbun.com/`
+
+Common places people use for public hosting or a VPS:
+
+- DigitalOcean: `https://www.digitalocean.com/`
+- Hetzner: `https://www.hetzner.com/`
+- Railway: `https://railway.com/`
+- Render: `https://render.com/`
+- Fly.io: `https://fly.io/`
+
+Common reverse proxy or edge options:
+
+- NGINX: `https://nginx.org/`
+- Caddy: `https://caddyserver.com/`
+- Cloudflare Tunnel: `https://www.cloudflare.com/products/tunnel/`
+
+Those are just examples. Use whatever actually gives you inbound HTTPS and a process you control.
+
+## Map Rendering
+
+Render an ER:LC map (`3121x3121`) with player markers that use Roblox avatars.
+
+```js
+const result = await client.map.render();
+
+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 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",
+});
+```
+
+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[]`
+- `mapUrl?: string`
+- `season?: string`
+- `type?: string`
+- `mapSeason?: string`
+- `mapType?: string`
+- `coordinateBounds?: { minX, maxX, minY, maxY, invertY? }`
+- `clampToMap?: boolean`
+- `robloxHeadshotSize?: string`
+- `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`
+- `skipped`
+- `requestedUserIds`
+- `unmatchedUserIds`
+
+## Events
+
+- `ready`
+- `playerJoin`
+- `playerLeave`
+- `kill`
+- `vehicleSpawn`
+- `vehicleDespawn`
+- `queueUpdate`
+- `staffUpdate`
+- `modCall`
+- `emergencyCall`
+- `commandLog`
+- `logCommand`
+- `serverUpdate`
+- `webhook`
+- `webhookCommand`
+- `webhookEmergencyCall`
+- `error`
+- `disconnect`
+
+Alias event names are also supported with `client.on(...)`:
+
+- `onReady`
+- `onJoin`
+- `onLeave`
+- `onKill`
+- `onVehicleSpawn`
+- `onVehicleDespawn`
+- `onQueueUpdate`
+- `onStaffUpdate`
+- `onModCall`
+- `onEmergencyCall`
+- `onCommandLog`
+- `onLogCommand`
+- `onServerUpdate`
+- `onApiRequest`
+- `onWebhook`
+- `onWebhookCommand`
+- `onWebhookEmergencyCall`
+- `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 or reset.
+
+By default, requests are serialized (`strictSerial: true`) so this client does not spray parallel requests at the API.
+
+## 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`)