palworld-api 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# palworld-api
+
+TypeScript/Node.js client for the Palworld dedicated server REST API.
+
+## Installation
+
+```bash
+npm install palworld-api
+```
+
+## Usage
+
+```typescript
+import { PalworldAPI } from "palworld-api";
+
+const api = new PalworldAPI("http://localhost:8212", "admin password");
+
+const info = await api.getServerInfo();
+console.log(info);
+
+const players = await api.getPlayerList();
+console.log(players);
+
+await api.makeAnnouncement("Server restarting in 5 minutes");
+await api.kickPlayer("steam_0:12345", "Cheating");
+```
+
+All methods return either the parsed response data or an `{ error: string }`
+object on failure — no exceptions are thrown.
+
+```typescript
+const result = await api.getServerMetrics();
+if ("error" in result) {
+  console.error(result.error);
+} else {
+  console.log(result.serverfps);
+}
+```
+
+## API
+
+- `getServerInfo()`
+- `getPlayerList()`
+- `getServerMetrics()`
+- `getServerSettings()`
+- `kickPlayer(userid, message)`
+- `banPlayer(userid, message)`
+- `unbanPlayer(userid)`
+- `saveServerState()`
+- `makeAnnouncement(message)`
+- `shutdownServer(waittime, message)`
+- `stopServer()`
+
+## Development
+
+```bash
+npm install
+npm run build
+```
+
+## Testing
+
+Live integration tests run against a real Palworld dedicated server. Edit
+`test/index.test.ts` and set `SERVER_URL`, `USERNAME`, `PASSWORD`, and
+`TEST_USER_ID` to match your server, then run:
+
+```bash
+npm test
+```
+
+`shutdownServer` and `stopServer` tests are skipped by default since they take
+the server offline. Remove `.skip` only when intentionally testing shutdown.
+
+## License
+
+MIT
+
+## Author
+
+[KJAyano](https://github.com/KJAyano)
+
+Repository: [github.com/KJAyano/palworld-api](https://github.com/KJAyano/palworld-api)

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+export interface ErrorResult {
+    error: string;
+}
+export type ApiResult<T> = T | ErrorResult;
+export interface ServerInfo {
+    version: string;
+    servername: string;
+    description: string;
+    worldguid: string;
+}
+export interface PlayerInfo {
+    name: string;
+    accountName: string;
+    playerId: string;
+    userId: string;
+    ip: string;
+    ping: number;
+    location_x: number;
+    location_y: number;
+    level: number;
+    building_count: number;
+}
+export interface PlayerListResponse {
+    players: PlayerInfo[];
+}
+export interface ServerMetrics {
+    serverfps: number;
+    currentplayernum: number;
+    serverframetime: number;
+    maxplayernum: number;
+    uptime: number;
+    basecampnum: number;
+    days: number;
+}
+export interface ServerSettings {
+    Difficulty: string;
+    DayTimeSpeedRate: number;
+    NightTimeSpeedRate: number;
+    ExpRate: number;
+    PalCaptureRate: number;
+    PalSpawnNumRate: number;
+    PalDamageRateAttack: number;
+    PalDamageRateDefense: number;
+    PlayerDamageRateAttack: number;
+    PlayerDamageRateDefense: number;
+    PlayerStomachDecreaceRate: number;
+    PlayerStaminaDecreaceRate: number;
+    PlayerAutoHPRegeneRate: number;
+    PlayerAutoHpRegeneRateInSleep: number;
+    PalStomachDecreaceRate: number;
+    PalStaminaDecreaceRate: number;
+    PalAutoHPRegeneRate: number;
+    PalAutoHpRegeneRateInSleep: number;
+    BuildObjectDamageRate: number;
+    BuildObjectDeteriorationDamageRate: number;
+    CollectionDropRate: number;
+    CollectionObjectHpRate: number;
+    CollectionObjectRespawnSpeedRate: number;
+    EnemyDropItemRate: number;
+    DeathPenalty: string;
+    bEnablePlayerToPlayerDamage: boolean;
+    bEnableFriendlyFire: boolean;
+    bEnableInvaderEnemy: boolean;
+    bActiveUNKO: boolean;
+    bEnableAimAssistPad: boolean;
+    bEnableAimAssistKeyboard: boolean;
+    DropItemMaxNum: number;
+    DropItemMaxNum_UNKO: number;
+    BaseCampMaxNum: number;
+    BaseCampWorkerMaxNum: number;
+    DropItemAliveMaxHours: number;
+    bAutoResetGuildNoOnlinePlayers: boolean;
+    AutoResetGuildTimeNoOnlinePlayers: number;
+    GuildPlayerMaxNum: number;
+    PalEggDefaultHatchingTime: number;
+    WorkSpeedRate: number;
+    bIsMultiplay: boolean;
+    bIsPvP: boolean;
+    bCanPickupOtherGuildDeathPenaltyDrop: boolean;
+    bEnableNonLoginPenalty: boolean;
+    bEnableFastTravel: boolean;
+    bIsStartLocationSelectByMap: boolean;
+    bExistPlayerAfterLogout: boolean;
+    bEnableDefenseOtherGuildPlayer: boolean;
+    CoopPlayerMaxNum: number;
+    ServerPlayerMaxNum: number;
+    ServerName: string;
+    ServerDescription: string;
+    PublicPort: number;
+    PublicIP: string;
+    RCONEnabled: boolean;
+    RCONPort: number;
+    Region: string;
+    bUseAuth: boolean;
+    BanListURL: string;
+    RESTAPIEnabled: boolean;
+    RESTAPIPort: number;
+    bShowPlayerList: boolean;
+    AllowConnectPlatform: string;
+    bIsUseBackupSaveData: boolean;
+    LogFormatType: string;
+}
+export declare class PalworldAPI {
+    private serverUrl;
+    private client;
+    constructor(serverUrl: string, password: string, username?: string, timeoutMs?: number);
+    private toErrorResult;
+    fetch<T>(endpoint: string): Promise<ApiResult<T>>;
+    post<T>(endpoint: string, payload?: Record<string, unknown>): Promise<ApiResult<T>>;
+    getServerInfo(): Promise<ApiResult<ServerInfo>>;
+    getPlayerList(): Promise<ApiResult<PlayerListResponse>>;
+    getServerMetrics(): Promise<ApiResult<ServerMetrics>>;
+    getServerSettings(): Promise<ApiResult<ServerSettings>>;
+    kickPlayer(userid: string, message: string): Promise<ApiResult<unknown>>;
+    banPlayer(userid: string, message: string): Promise<ApiResult<unknown>>;
+    unbanPlayer(userid: string): Promise<ApiResult<unknown>>;
+    saveServerState(): Promise<ApiResult<unknown>>;
+    makeAnnouncement(message: string): Promise<ApiResult<unknown>>;
+    shutdownServer(waittime: number, message: string): Promise<ApiResult<unknown>>;
+    stopServer(): Promise<ApiResult<unknown>>;
+}
+export default PalworldAPI;

package/dist/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PalworldAPI = void 0;
+const axios_1 = __importDefault(require("axios"));
+class PalworldAPI {
+    constructor(serverUrl, password, username = "admin", timeoutMs) {
+        this.serverUrl = serverUrl;
+        const token = Buffer.from(`${username}:${password}`).toString("base64");
+        this.client = axios_1.default.create({
+            baseURL: serverUrl,
+            maxBodyLength: Infinity,
+            maxContentLength: Infinity,
+            timeout: timeoutMs,
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Basic ${token}`,
+            },
+        });
+    }
+    toErrorResult(error) {
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = error;
+            if (axiosError.code === "ECONNABORTED" || axiosError.code === "ETIMEDOUT") {
+                return { error: "Request timeout" };
+            }
+            if (axiosError.response) {
+                return {
+                    error: `Client error ${axiosError.response.status}: ${axiosError.response.statusText}`,
+                };
+            }
+            if (axiosError.request) {
+                return { error: "Connection error" };
+            }
+        }
+        if (error instanceof Error) {
+            return { error: error.message };
+        }
+        return { error: String(error) };
+    }
+    async fetch(endpoint) {
+        try {
+            const response = await this.client.get(endpoint);
+            return response.data;
+        }
+        catch (error) {
+            return this.toErrorResult(error);
+        }
+    }
+    async post(endpoint, payload) {
+        try {
+            const response = await this.client.post(endpoint, payload ?? {});
+            return response.data;
+        }
+        catch (error) {
+            return this.toErrorResult(error);
+        }
+    }
+    async getServerInfo() {
+        return this.fetch("/v1/api/info");
+    }
+    async getPlayerList() {
+        return this.fetch("/v1/api/players");
+    }
+    async getServerMetrics() {
+        return this.fetch("/v1/api/metrics");
+    }
+    async getServerSettings() {
+        return this.fetch("/v1/api/settings");
+    }
+    async kickPlayer(userid, message) {
+        return this.post("/v1/api/kick", { userid, message });
+    }
+    async banPlayer(userid, message) {
+        return this.post("/v1/api/ban", { userid, message });
+    }
+    async unbanPlayer(userid) {
+        return this.post("/v1/api/unban", { userid });
+    }
+    async saveServerState() {
+        return this.post("/v1/api/save");
+    }
+    async makeAnnouncement(message) {
+        return this.post("/v1/api/announce", { message });
+    }
+    async shutdownServer(waittime, message) {
+        return this.post("/v1/api/shutdown", { waittime, message });
+    }
+    async stopServer() {
+        return this.post("/v1/api/stop");
+    }
+}
+exports.PalworldAPI = PalworldAPI;
+exports.default = PalworldAPI;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "palworld-api",
+  "version": "1.0.0",
+  "description": "TypeScript/Node.js client for the Palworld dedicated server REST API",
+  "author": "KJAyano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KJAyano/palworld-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KJAyano/palworld-api/issues"
+  },
+  "homepage": "https://github.com/KJAyano/palworld-api#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "palworld",
+    "rest-api",
+    "palworld restapi",
+    "pal-restapi"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.3",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.5.0"
+  }
+}