erlc-v2 1.0.1 → 1.1.1

package/README.md

@@ -4,15 +4,23 @@ JavaScript client for the ER:LC API v2.
 
 Built for Node 18+.
 
-## Stable Release
-
-This wrapper is now on a stable release track (`1.0.0+`).
+## 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
 
-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.
+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. Always monitor your integration and respect PRC API rules and headers.
+This project is provided as-is. Keep an eye on your own integration and follow the PRC API rules.
 
 ## Install
 
@@ -27,7 +35,9 @@ const { Client } = require("erlc-v2");
 
 const client = new Client({
   serverKey: "YOUR_SERVER_KEY",
-  // globalKey: "YOUR_GLOBAL_KEY", // optional
+  polling: {
+    enabled: true,
+  },
 });
 
 client.on("disconnect", ({ reason, error }) => {
@@ -39,11 +49,14 @@ async function main() {
     players: true,
     staff: true,
     queue: true,
+    vehicles: true,
+    emergencyCalls: true,
   });
 
   console.log("Server:", snapshot.name);
   console.log("Players:", `${snapshot.currentPlayers}/${snapshot.maxPlayers}`);
-  console.log("Players payload:", snapshot.players.length);
+  console.log("Vehicles:", snapshot.vehicles.length);
+  console.log("Emergency calls:", snapshot.emergencyCalls.length);
 }
 
 main()
@@ -73,23 +86,33 @@ 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`)
+    provider?: "memory" | "redis", // default: auto
+    redisUrl?: string,
     redisPrefix?: string, // default: "erlc-v2:cache"
-    redisClient?: object, // optional pre-configured Redis client
+    redisClient?: object,
   },
   rateLimit?: {
     enabled?: boolean, // default: true
-    strictSerial?: boolean, // default: true (global one-at-a-time queue)
+    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 (min enforced: 250)
+    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
+  },
 });
 ```
 
@@ -146,6 +169,7 @@ const { Client } = require("erlc-v2");
 Core:
 
 - `await client.server.fetch(flags, requestOptions?)`
+- `await client.commands.execute(command)`
 - `client.destroy()`
 - `client.cache.clear()`
 
@@ -159,9 +183,13 @@ Convenience methods:
 - `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()`
-- `await client.commands.execute(":h Hey everyone!")` (v1 endpoint)
 
 ### Fetch Flags
 
@@ -172,6 +200,7 @@ Convenience methods:
 - `killLogs` -> `KillLogs`
 - `commandLogs` -> `CommandLogs`
 - `modCalls` -> `ModCalls`
+- `emergencyCalls` -> `EmergencyCalls`
 - `vehicles` -> `Vehicles`
 
 ### Request Options
@@ -180,12 +209,63 @@ Convenience methods:
 - `cacheTtlMs?: number`
 - `dedupe?: boolean`
 
-### Command Execution (v1)
+## 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:
 
-`client.commands.execute(command)` sends a POST request to `/v1/server/command`.
+```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 (request will be rejected before hitting the API):
+Blocked by client policy:
 
 - `:view`
 - `:to`
@@ -205,10 +285,156 @@ Blocked by client policy (request will be rejected before hitting the API):
 Example:
 
 ```js
-await client.commands.execute(":h Hey everyone!");
-await client.commands.execute(":log recentban He was trolling!");
+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.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);
+  console.log("Command:", payload.command);
+  console.log("Args:", payload.args);
+  console.log("Origin:", payload.origin);
+});
+
+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`
+
+This webhook is for custom `;` commands and emergency calls. It is not for normal `:` commands from the command endpoint.
+
+For custom `;` commands, `payload.command`, `payload.args`, and `payload.origin` are usually the fields you want.
+
+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.
@@ -216,7 +442,6 @@ 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);
 ```
@@ -231,16 +456,6 @@ const fallBlank = await client.map.render({
   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",
@@ -251,7 +466,7 @@ 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)
+  mapUrl: "https://example.com/my-map.png",
 });
 ```
 
@@ -268,15 +483,15 @@ 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`)
+- `players?: any[]`
+- `mapUrl?: string`
+- `season?: string`
+- `type?: string`
+- `mapSeason?: string`
+- `mapType?: string`
 - `coordinateBounds?: { minX, maxX, minY, maxY, invertY? }`
-- `clampToMap?: boolean` (default: `true`)
-- `robloxHeadshotSize?: string` (default: `"150x150"`)
+- `clampToMap?: boolean`
+- `robloxHeadshotSize?: string`
 - `marker?: { outerRadius, innerRadius, tipLength, tipWidth, fillColor, shadow }`
 
 Map size is fixed to `3121x3121`.
@@ -285,10 +500,10 @@ 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)
+- `players`
+- `skipped`
+- `requestedUserIds`
+- `unmatchedUserIds`
 
 ## Events
 
@@ -301,11 +516,14 @@ Result shape:
 - `queueUpdate`
 - `staffUpdate`
 - `modCall`
+- `emergencyCall`
 - `commandLog`
-- `logCommand` (only when command starts with `:log`)
-- `serverUpdate`
+- `logCommand`
+- `serverUpdate`
+- `webhook`
+- `webhookEmergencyCall`
 - `error`
-- `disconnect` (`{ reason, error }`)
+- `disconnect`
 
 Alias event names are also supported with `client.on(...)`:
 
@@ -318,9 +536,13 @@ Alias event names are also supported with `client.on(...)`:
 - `onQueueUpdate`
 - `onStaffUpdate`
 - `onModCall`
+- `onEmergencyCall`
 - `onCommandLog`
 - `onLogCommand`
-- `onServerUpdate`
+- `onServerUpdate`
+- `onApiRequest`
+- `onWebhook`
+- `onWebhookEmergencyCall`
 - `onError`
 - `onDisconnect`
 
@@ -350,10 +572,9 @@ Requests are automatically bucketed using API response headers:
 - `X-RateLimit-Remaining`
 - `X-RateLimit-Reset`
 
-On `429`, the client blocks the affected bucket until retry time/reset.
+On `429`, the client blocks the affected bucket until retry time or 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.
+By default, requests are serialized (`strictSerial: true`) so this client does not spray parallel requests at the API.
 
 ## Errors
 
@@ -372,10 +593,10 @@ The client normalizes errors into classes:
 
 Terminal key errors (`2002`, `2004`) trigger disconnect and stop polling.
 
-Repeated `403` responses can also trigger disconnect (reason: `"unauthorized"`).
+Repeated `403` responses can also trigger disconnect (`reason: "unauthorized"`).
 
 ## Notes
 
 - API base URL: `https://api.policeroleplay.community`
-- `Server-Key` is required for requests
+- `server-key` is required for requests
 - `Authorization` is optional (`globalKey`)