@libertytools/libertyjs 1.0.1

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@libertytools/libertyjs",
+  "version": "1.0.1",
+  "description": "An SDK to help developers create apps for the ER:LC Private Server API.",
+  "author": "novix",
+  "license": "ISC",
+
+  "type": "module",
+
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+
+  "files": [
+    "src"
+  ],
+
+  "keywords": [
+    "erlc",
+    "police roleplay community",
+    "liberty county"
+  ],
+
+  "engines": {
+    "node": ">=18"
+  }
+}

package/readme.md

@@ -0,0 +1,359 @@
+# LibertyJS
+
+A lightweight SDK for the **ER:LC Private Server API**, designed to simplify requests, enforce rate limits, and provide structured error handling.
+
+---
+
+## Features
+
+* Automatic **rate limit handling** (GET + POST)
+* Built-in **API key validation**
+* **403 fail-safe** (halts after repeated failures)
+* Optional **webhook integration**
+* Structured **error responses**
+* Automatic **JSON handling for POST requests**
+* Built-in **command validation + argument checking**
+
+---
+
+## Importing
+
+```js
+import LibertyJS from "libertyjs";
+```
+
+---
+
+## Initialization
+
+```js
+const LJS = new LibertyJS({
+    SERVER_KEY: process.env.SERVER_KEY,
+    PRIVATE_SERVER_API: "https://api.policeroleplay.community/v2/", // optional
+    WEBHOOK_URL: process.env.WEBHOOK_URL, // optional
+    WEBHOOK_TOKEN: process.env.WEBHOOK_TOKEN // required if WEBHOOK_URL is used
+});
+```
+
+---
+
+## Configuration Options
+
+| Option               | Required | Description                           |
+| -------------------- | -------- | ------------------------------------- |
+| `SERVER_KEY`         | ✅        | ER:LC private server API key          |
+| `PRIVATE_SERVER_API` | ❌        | Base API URL (defaults to PRC v2)     |
+| `WEBHOOK_URL`        | ❌        | Webhook base URL                      |
+| `WEBHOOK_TOKEN`      | ⚠️       | Required if `WEBHOOK_URL` is provided |
+
+---
+
+# Methods
+
+---
+
+## `getPrivateServerAPI(options, includeInvalid?)`
+
+Fetch data from the ER:LC Private Server API.
+
+### Example
+
+```js
+const data = await LJS.getPrivateServerAPI([
+    "Players",
+    "Staff"
+]);
+```
+
+---
+
+### Parameters
+
+| Parameter        | Type       | Description                         |
+| ---------------- | ---------- | ----------------------------------- |
+| `options`        | `string[]` | List of data types to request       |
+| `includeInvalid` | `boolean`  | Include invalid options in response |
+
+---
+
+### Valid Options
+
+* Players
+* Staff
+* JoinLogs
+* Queue
+* KillLogs
+* CommandLogs
+* ModCalls
+* EmergencyCalls
+* Vehicles
+
+---
+
+### Behavior
+
+* Automatically appends `/server`
+* Builds query string internally
+* Filters invalid options
+* Waits automatically if rate-limited
+
+---
+
+### Example with Invalid Tracking
+
+```js
+const res = await LJS.getPrivateServerAPI(
+    ["Players", "InvalidOption"],
+    true
+);
+
+console.log(res);
+/*
+{
+  data: {...},
+  invalidOptions: ["InvalidOption"]
+}
+*/
+```
+
+---
+
+### Errors
+
+#### Invalid Input
+
+```js
+{
+    error: "invalid_input",
+    message: "[LibertyJS.getPrivateServerAPI]: Options must be an array"
+}
+```
+
+---
+
+#### Forbidden (after 2 failures)
+
+```js
+{
+    error: "forbidden",
+    message: "[LibertyJS]: Received a 403 error 2 times, suspending API calls as the server key may be invalid"
+}
+```
+
+---
+
+#### API Error
+
+```js
+{
+    error: "api-error",
+    message: "[LibertyJS]: Encountered an error while attempting to fetch <url>",
+    apiResponse: { ... }
+}
+```
+
+---
+
+## `sendPrivateServerCommand(commands)`
+
+Send one or more commands to the private server.
+
+---
+
+### Example
+
+```js
+const res = await LJS.sendPrivateServerCommand([
+    ":h Hello world!",
+    ":kick PlayerName Spamming"
+]);
+```
+
+---
+
+### Parameters
+
+| Parameter  | Type       | Description              |
+| ---------- | ---------- | ------------------------ |
+| `commands` | `string[]` | Array of command strings |
+
+---
+
+### Behavior
+
+* Validates:
+
+  * Command existence
+  * Argument count
+* Ignores:
+
+  * Invalid commands
+  * Incorrect argument usage
+* Sends commands **sequentially**
+* Tracks success/failure per command
+
+---
+
+### Response
+
+```js
+{
+  successes: 2,
+  failures: 0,
+  failureReasons: []
+}
+```
+
+---
+
+### Failure Example
+
+```js
+{
+  successes: 1,
+  failures: 1,
+  failureReasons: [
+    {
+      command: ":kick Player",
+      apiResponse: { ... }
+    }
+  ]
+}
+```
+
+---
+
+### Errors
+
+#### Invalid Input
+
+```js
+{
+    error: "invalid_input",
+    message: "[LibertyJS.sendPrivateServerCommand]: Options must be an array"
+}
+```
+
+#### Empty Array
+
+```js
+{
+    error: "invalid_input",
+    message: "[LibertyJS.sendPrivateServerCommand]: Options must have at least one item"
+}
+```
+
+---
+
+# Webhook API
+
+> Webhooks are accessed via a **nested object**, not top-level methods.
+
+---
+
+## `webhook.status()`
+
+Check webhook health.
+
+### Example
+
+```js
+const res = await LJS.webhook.status();
+```
+
+---
+
+### Errors
+
+#### Webhook Disabled
+
+```js
+{
+    error: "webhook_disabled",
+    message: "[LibertyJS.webhook.status]: Webhook is not configured"
+}
+```
+
+---
+
+## `webhook.events()`
+
+Fetch webhook events.
+
+### Example
+
+```js
+const events = await LJS.webhook.events();
+```
+
+---
+
+### Errors
+
+#### Webhook Disabled
+
+```js
+{
+    error: "webhook_disabled",
+    message: "[LibertyJS.webhook.events]: Webhook is not configured"
+}
+```
+
+---
+
+# Internal Behavior
+
+---
+
+## Rate Limiting
+
+Tracked separately for GET and POST:
+
+```js
+{
+    get: { limit, remaining, reset },
+    post: { limit, remaining, reset }
+}
+```
+
+---
+
+### Details
+
+* Uses headers:
+
+  * `X-RateLimit-Limit`
+  * `X-RateLimit-Remaining`
+  * `X-RateLimit-Reset`
+* Automatically delays requests when:
+
+```
+remaining === 0 && currentTime < reset
+```
+
+* Logs:
+
+```
+[LibertyJS]: Rate limited (GET/POST). Waiting Xs
+```
+
+---
+
+## Forbidden Protection
+
+After **2 consecutive `403` responses**:
+
+* All future API calls are blocked
+* Prevents invalid API key spam
+
+---
+
+## Request Handling (`#fetchAPI`)
+
+Handles:
+
+* Authentication headers (`server-key`)
+* JSON parsing (safe fallback to `null`)
+* Rate limit tracking
+* Error normalization
+* Automatic JSON stringification for POST bodies

package/src/index.js

@@ -0,0 +1,309 @@
+export default class LibertyJS {
+    #SERVER_KEY;
+    #PRIVATE_SERVER_API;
+    #useWebhook;
+    #WEBHOOK_URL;
+    #WEBHOOK_TOKEN;
+    #rateLimits;
+    #resStatus;
+
+    constructor({
+        SERVER_KEY,
+        PRIVATE_SERVER_API = "https://api.policeroleplay.community/v2/",
+        WEBHOOK_URL,
+        WEBHOOK_TOKEN
+    } = {}) {
+        if (!SERVER_KEY) {
+            throw new Error("[LibertyJS]: SERVER_KEY is required");
+        }
+
+        this.#SERVER_KEY = SERVER_KEY;
+        this.#PRIVATE_SERVER_API = PRIVATE_SERVER_API;
+
+        if (WEBHOOK_URL && !WEBHOOK_TOKEN) {
+            throw new Error("[LibertyJS]: WEBHOOK_TOKEN is required if you are using a webhook");
+        }
+
+        this.#useWebhook = Boolean(WEBHOOK_URL && WEBHOOK_TOKEN);
+
+        if (WEBHOOK_URL && WEBHOOK_TOKEN) {
+            this.#WEBHOOK_URL = WEBHOOK_URL;
+            this.#WEBHOOK_TOKEN = WEBHOOK_TOKEN;
+        }
+
+        this.#rateLimits = {
+            get: { limit: null, remaining: null, reset: null },
+            post: { limit: null, remaining: null, reset: null }
+        };
+
+        this.#resStatus = {
+            forbiddenErrors: 0
+        };
+    }
+
+    #wait(seconds) {
+        return new Promise(resolve => setTimeout(resolve, seconds * 1000));
+    }
+
+    async #fetchAPI(url, options = {}) {
+        if (!this.#SERVER_KEY) {
+            return {
+                error: "invalid_env",
+                message: "[LibertyJS]: SERVER_KEY was not provided in a .env file"
+            };
+        }
+
+        if (this.#resStatus.forbiddenErrors >= 2) {
+            return {
+                error: "forbidden",
+                message: "[LibertyJS]: Received a 403 error 2 times, suspending API calls as the server key may be invalid"
+            };
+        }
+
+        const isPRC = url.startsWith("https://api.policeroleplay.community/");
+        const method = (options.method || "GET").toUpperCase();
+
+        const headers = { ...(options.headers || {}) };
+
+        let body = options.body;
+        if (method === "POST" && body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = typeof body === "string" ? body : JSON.stringify(body);
+        }
+
+        if (isPRC) {
+            headers["server-key"] = this.#SERVER_KEY;
+        }
+
+        const currentTime = Math.floor(Date.now() / 1000);
+
+        const handleRateLimit = async (rl) => {
+            if (rl.reset && rl.remaining === 0 && currentTime < rl.reset) {
+                const seconds = Math.max(0, rl.reset - currentTime);
+                console.log(`[LibertyJS]: Rate limited (${method}). Waiting ${seconds}s`);
+                await this.#wait(seconds);
+            }
+        };
+
+        if (isPRC) {
+            if (method === "GET") await handleRateLimit(this.#rateLimits.get);
+            if (method === "POST") await handleRateLimit(this.#rateLimits.post);
+        }
+
+        const res = await fetch(url, {
+            ...options,
+            method,
+            headers,
+            body
+        });
+
+        let data;
+        try {
+            data = await res.json();
+        } catch {
+            data = null;
+        }
+
+        if (!res.ok) {
+            if (res.status === 403 && isPRC) {
+                this.#resStatus.forbiddenErrors++;
+            }
+
+            return {
+                error: "api-error",
+                message: `[LibertyJS]: Encountered an error while attempting to fetch ${url}`,
+                apiResponse: data
+            };
+        }
+
+        if (isPRC) {
+            const target = method === "GET"
+                ? this.#rateLimits.get
+                : this.#rateLimits.post;
+
+            target.reset = Number(res.headers.get("X-RateLimit-Reset"));
+            target.limit = Number(res.headers.get("X-RateLimit-Limit"));
+            target.remaining = Number(res.headers.get("X-RateLimit-Remaining"));
+        }
+
+        return data;
+    }
+
+    async getPrivateServerAPI(options = [], includeInvalid = false) {
+        const valid = [
+            "Players",
+            "Staff",
+            "JoinLogs",
+            "Queue",
+            "KillLogs",
+            "CommandLogs",
+            "ModCalls",
+            "EmergencyCalls",
+            "Vehicles"
+        ];
+
+        if (!Array.isArray(options)) {
+            console.error("[LibertyJS.getPrivateServerAPI]: Options must be an array");
+            return {
+                error: "invalid_input",
+                message: "[LibertyJS.getPrivateServerAPI]: Options must be an array"
+            };
+        }
+
+        const params = [];
+        const invalidOptions = [];
+
+        for (const opt of options) {
+            if (valid.includes(opt)) {
+                params.push(`${opt}=true`);
+            } else {
+                console.log(`[LibertyJS]: Invalid option "${String(opt)}"`);
+                invalidOptions.push(opt);
+            }
+        }
+
+        const query = params.length ? `?${params.join("&")}` : "";
+        const url = this.#PRIVATE_SERVER_API + "server" + query;
+
+        if (!includeInvalid) {
+            return await this.#fetchAPI(url);
+        }
+
+        return {
+            data: await this.#fetchAPI(url),
+            invalidOptions
+        };
+    }
+
+    async sendPrivateServerCommand(options = []) {
+        const url = this.#PRIVATE_SERVER_API + "server/command";
+
+        const valid = {
+            ":wanted": ["Player"],
+            ":time": ["Number"],
+            ":stopfire": [],
+            ":respawn": ["Player"],
+            ":tp": ["Player", "Player"],
+            ":startnearfire": ["String"],
+            ":jail": ["Player"],
+            ":pt": ["Number"],
+            ":h": ["String"],
+            ":m": ["String"],
+            ":pm": ["Player", "String"],
+            ":refresh": ["Player"],
+            ":bring": ["Player"],
+            ":heal": ["Player"],
+            ":kick": ["Player", "String"],
+            ":startfire": ["String"],
+            ":unwanted": ["Player"],
+            ":prty": ["Number"],
+            ":stopdumpsterfire": [],
+            ":helper": ["Player/UserId"],
+            ":shutdown": [],
+            ":weather": ["String"],
+            ":unmod": ["Player/UserId"],
+            ":unloadlayout": ["String"],
+            ":unban": ["String"],
+            ":mod": ["Player/UserId"],
+            ":ban": ["Player/UserId"],
+            ":unhelper": ["Player/UserId"],
+            ":log": ["String"],
+            ":kill": ["Player"],
+            ":unadmin": ["Player/UserId"],
+            ":admin": ["Player/UserId"],
+            ":loadlayout": ["String"]
+        };
+
+        if (!Array.isArray(options)) {
+            console.error("[LibertyJS.sendPrivateServerCommand]: Options must be an array");
+            return {
+                error: "invalid_input",
+                message: "[LibertyJS.sendPrivateServerCommand]: Options must be an array"
+            };
+        }
+
+        if (options.length === 0) {
+            console.error("[LibertyJS.sendPrivateServerCommand]: Options must have at least one item");
+            return {
+                error: "invalid_input",
+                message: "[LibertyJS.sendPrivateServerCommand]: Options must have at least one item"
+            };
+        }
+
+        const commands = [];
+
+        for (const cmd of options) {
+            if (!cmd.startsWith(":")) continue;
+
+            const parts = cmd.trim().split(" ");
+            const name = parts[0];
+            const args = parts.slice(1);
+            const schema = valid[name];
+
+            if (!schema) {
+                console.error(`[LibertyJS]: Unsupported command "${name}"`);
+                continue;
+            }
+
+            const validArgs =
+                (schema.at(-1) === "String" && args.length >= schema.length) ||
+                (schema.at(-1) !== "String" && args.length === schema.length);
+
+            if (validArgs) {
+                commands.push(cmd);
+            } else {
+                console.log(`[LibertyJS]: "${name}" requires ${schema.length}${schema.at(-1) === "String" ? "+" : ""} args`);
+            }
+        }
+
+        let successes = 0;
+        let failures = 0;
+        const failureReasons = [];
+
+        for (const command of commands) {
+            const res = await this.#fetchAPI(url, {
+                method: "POST",
+                body: command
+            });
+
+            if (!res?.error) {
+                successes++;
+            } else {
+                failures++;
+                failureReasons.push({
+                    command,
+                    apiResponse: res.apiResponse
+                });
+            }
+        }
+
+        return { successes, failures, failureReasons };
+    }
+
+    webhook = {
+        status: async () => {
+            if (!this.#useWebhook) {
+                return {
+                    error: "webhook_disabled",
+                    message: "[LibertyJS.webhook.status]: Webhook is not configured"
+                };
+            }
+
+            const url = `${this.#WEBHOOK_URL}health`;
+
+            return await this.#fetchAPI(url, { method: "GET" });
+        },
+        events: async () => {
+            if (!this.#useWebhook) {
+                return {
+                    error: "webhook_disabled",
+                    message: "[LibertyJS.webhook.events]: Webhook is not configured"
+                };
+            }
+
+            const url = `${this.#WEBHOOK_URL}webhook/${this.#WEBHOOK_TOKEN}/events`;
+
+            return await this.#fetchAPI(url, { method: "GET" });
+        }
+    };
+}