@srvquery/protocol-fivem 0.0.1-next.0

package/dist/net/server-id.d.ts

@@ -0,0 +1,14 @@
+import { type CreateHttpClientParams } from "@srvquery/core";
+/**
+ * Resolves a Cfx.re server id (the short code used in join links such as
+ * `https://cfx.re/join/<join>`) to a host and port pair, by querying the public Cfx.re server
+ * list API for the server's advertised connect endpoints.
+ *
+ * @param id The Cfx.re server id.
+ * @param timeout Time in milliseconds to wait for the lookup before aborting.
+ * @returns The resolved host and port pair for the server's HTTP query endpoints.
+ * @throws {QueryTransportError} If the id is unknown, the lookup times out, or it resolves to no
+ * usable IPv4 endpoint.
+ */
+export declare const resolveServerId: (id: string, timeout?: number) => Promise<CreateHttpClientParams>;
+//# sourceMappingURL=server-id.d.ts.map

package/dist/net/server-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-id.d.ts","sourceRoot":"","sources":["../../src/net/server-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAQlG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,OACtB,MAAM,uBAET,OAAO,CAAC,sBAAsB,CAuDhC,CAAC"}

package/dist/packet/formatting.d.ts

@@ -0,0 +1,5 @@
+/** Strips FiveM/RedM `^`-prefixed color and formatting codes from a string. */
+export declare const stripFiveMFormattingCodes: (value: string) => string;
+/** Recursively strips FiveM/RedM formatting codes from every string found in `value`. */
+export declare const deepStripFiveMFormattingCodes: <T>(value: T) => T;
+//# sourceMappingURL=formatting.d.ts.map

package/dist/packet/formatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../src/packet/formatting.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,UAAW,MAAM,KAAG,MACd,CAAC;AAE7C,yFAAyF;AACzF,eAAO,MAAM,6BAA6B,GAAI,CAAC,SAAS,CAAC,KAAG,CAS3D,CAAC"}

package/dist/packet/schema.d.ts

@@ -0,0 +1,67 @@
+import z from "zod";
+/**
+ * Validates the `vars` map returned by a FiveM/RedM `info.json` query.
+ *
+ * `vars` mirrors whatever `set`/`sets` convars a server operator has defined, so there is no fixed, documented set of keys. The fields below are commonly present across public servers (surfaced by the Cfx server list and/or txAdmin) and are typed for convenience; any other convar is still preserved via the catch-all.
+ */
+export declare const FiveMVarsSchema: z.ZodObject<{
+    sv_projectName: z.ZodOptional<z.ZodString>;
+    sv_projectDesc: z.ZodOptional<z.ZodString>;
+    sv_maxClients: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodString>;
+    banner_connecting: z.ZodOptional<z.ZodString>;
+    banner_detail: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodString>>;
+/** Convar-style key/value pairs (`sv_hostname`, `sv_maxClients`, ...) reported by the server. */
+export type FiveMVars = z.infer<typeof FiveMVarsSchema>;
+/** Validates a FiveM/RedM `info.json` response. */
+export declare const FiveMServerInfoSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    icon: z.ZodOptional<z.ZodString>;
+    vars: z.ZodOptional<z.ZodObject<{
+        sv_projectName: z.ZodOptional<z.ZodString>;
+        sv_projectDesc: z.ZodOptional<z.ZodString>;
+        sv_maxClients: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodString>;
+        banner_connecting: z.ZodOptional<z.ZodString>;
+        banner_detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>>;
+    resources: z.ZodArray<z.ZodString>;
+    server: z.ZodString;
+}, z.core.$strip>;
+/** General server metadata, resources and convars returned by an `INFO` query. */
+export type FiveMServerInfo = z.infer<typeof FiveMServerInfoSchema>;
+/** Validates a single connected player entry returned by a `players.json` query. */
+export declare const FiveMPlayerSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    ping: z.ZodNumber;
+    identifiers: z.ZodArray<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Validates the player list returned by a FiveM/RedM `players.json` query. */
+export declare const FiveMPlayersSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    ping: z.ZodNumber;
+    identifiers: z.ZodArray<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** Connected player entry containing an ID, name, ping and identifiers. */
+export type FiveMPlayer = z.infer<typeof FiveMPlayerSchema>;
+/** Connected player entries returned by a FiveM/RedM `PLAYERS` query. */
+export type FiveMPlayers = z.infer<typeof FiveMPlayersSchema>;
+/** Validates a FiveM/RedM `dynamic.json` response. */
+export declare const FiveMDynamicSchema: z.ZodObject<{
+    hostname: z.ZodString;
+    gametype: z.ZodString;
+    mapname: z.ZodString;
+    clients: z.ZodCoercedNumber<unknown>;
+    sv_maxclients: z.ZodCoercedNumber<unknown>;
+    iv: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+/** Lightweight, server-browser-oriented summary returned by a `DYNAMIC` query. */
+export type FiveMDynamic = z.infer<typeof FiveMDynamicSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/packet/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/packet/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;iCAUL,CAAC;AAExB,iGAAiG;AACjG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,mDAAmD;AACnD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAMhC,CAAC;AAEH,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,oFAAoF;AACpF,eAAO,MAAM,iBAAiB;;;;;;iBAM5B,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB;;;;;;kBAA6B,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,sDAAsD;AACtD,eAAO,MAAM,kBAAkB;;;;;;;iBAO7B,CAAC;AAEH,kFAAkF;AAClF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,45 @@
+import { CreateHttpClientOptions, CreateHttpClientParams } from "@srvquery/core";
+import { type FiveMDynamic, type FiveMPlayers, type FiveMServerInfo } from "./packet/schema";
+/**
+ * Locates a FiveM/RedM server, either directly by `host`/`port` or by its Cfx.re server id (the
+ * short code used in join links such as `https://cfx.re/join/<id>`).
+ */
+export type FiveMServerLocator = (CreateHttpClientParams & {
+    id?: never;
+}) | {
+    id: string;
+    host?: never;
+    port?: never;
+};
+/** Connection and retry settings used to create a FiveM/RedM protocol client. */
+export type CreateFiveMProtocolParams = FiveMServerLocator & CreateHttpClientOptions;
+/** Endpoints exposed by an FXServer, keyed by their public `.json` path. */
+export type FiveMProtocolRequestOpcode = "INFO" | "PLAYERS" | "DYNAMIC";
+type FiveMProtocolQueryParams<Opcode extends FiveMProtocolRequestOpcode> = {
+    opcode: Opcode;
+    /** Strip FiveM/RedM `^`-prefixed color/formatting codes from every string in the response. */
+    stripFormattingCodes?: boolean;
+};
+type FiveMProtocolResponseMap = {
+    INFO: FiveMServerInfo;
+    PLAYERS: FiveMPlayers;
+    DYNAMIC: FiveMDynamic;
+};
+/** Client for querying FiveM and RedM (FXServer) servers. */
+export interface FiveMProtocol {
+    /** Queries one FXServer endpoint and resolves with its corresponding response model. */
+    query<Opcode extends FiveMProtocolRequestOpcode>(params: FiveMProtocolQueryParams<Opcode>): Promise<FiveMProtocolResponseMap[Opcode]>;
+}
+/**
+ * Creates a client for querying FiveM and RedM (FXServer) servers.
+ *
+ * The server can be located either by `host`/`port` or by its Cfx.re server id; when an id is
+ * given it is resolved to a host and port pair on first use and cached for the lifetime of the
+ * returned client.
+ *
+ * @param params Target server (by `host`/`port` or `id`) and HTTP transport settings.
+ * @returns A client whose `query` method returns the response type for the requested opcode.
+ */
+export declare const createFiveMProtocol: ({ protocol, timeout, retry, ...locator }: CreateFiveMProtocolParams) => FiveMProtocol;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAKvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,CAAC,sBAAsB,GAAG;IAAE,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,GACzC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE/C,iFAAiF;AACjF,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,GAAG,uBAAuB,CAAC;AAErF,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,KAAK,wBAAwB,CAAC,MAAM,SAAS,0BAA0B,IAAI;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,KAAK,CAAC,MAAM,SAAS,0BAA0B,EAC7C,MAAM,EAAE,wBAAwB,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;CAC9C;AAcD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,6CAK7B,yBAAyB,KAAG,aA8B9B,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@srvquery/protocol-fivem",
+  "version": "0.0.1-next.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "0.0.0",
+    "@srvquery/core": "0.0.1-next.0",
+    "@types/node": "^26.4.1",
+    "rolldown": "^1.2.7",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@srvquery/core": "0.0.1-next.0"
+  },
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}