Skip to content

README.md

Latest commit

 

History

History
151 lines (121 loc) · 5.34 KB

README.md

File metadata and controls

151 lines (121 loc) · 5.34 KB

PalDefender Rest Client (TypeScript)

npm version npm version license PalLink

An installable, type-safe TypeScript Wrapper for the PalDefender REST API. This package provides a high-level interface to manage Palworld servers with a focus on developer experience and intuitive "Smart Input" granting.

Install

npm install paldefender-rest-client

Quick Start

import { PalDefenderClient, PalId } from 'paldefender-rest-client';

const client = new PalDefenderClient({
    token: 'your-PD-Token', 
    host: '127.0.0.1',
    port: 17993
});

async function main() {
    // List all players (using alias)
    const { players } = await client.players();
    
    // Smart Input: Pass multiple items as separate arguments, 
    // single strings, or arrays. Duplicates are merged automatically!
    await client.giveItems("steam_76561198000000000", 
        "Stone", 
        { ItemId: "Stone", Count: 15 }, 
        "Wood"
    );
}

🆔 ID Parameter Support

For all functions targeting a player, the following formats are supported:

  • PlayerUID: The internal Palworld GUID (XXXXXXXX-0000-0000-0000-000000000000).
  • UserID: The platform-specific ID (steam_..., mac_..., gdk_..., or ps5_...).
  • NOTE: The mac id seems to be broken right now. Use UID if your player is playing on Mac Device.

Action Endpoints (Smart Granting)

All "give" and "tech" methods use a Uniform Rest Parameter system. You never have to worry about whether to pass an array or a single value—both work perfectly.

Items: giveItems(id, ...items)

Automatically aggregates counts for duplicate IDs (e.g., "Stone" + {ItemId: "Stone", Count: 5} = 6 Stone).

await client.giveItems(id, "Stone"); // Shorthand (Count: 1)
await client.giveItems(id, ["Stone", "Wood"]); // Single array
await client.giveItems(id, "Stone", { ItemId: "Wood", Count: 100 }); // Mixed rest params

Pals: givePals(id, ...pals)

Supports friendly PalName keys (e.g., "Anubis") or raw PalId values (e.g., "Alpaca").

import { PalId } from 'paldefender-rest-client';

await client.givePals(id, "Anubis"); // Level 1 shorthand
await client.givePals(id, PalId.Jetragon, { PalName: "Anubis", Level: 50 }); // Mixed

Eggs: givePalEggs(id, ...eggs)

Supports Egg IDs, detailed objects, or tuples for quick entry.

await client.givePalEggs(id, 
    "Egg_Dark_01",                       // Shorthand
    ["Egg_Dark_02", "Anubis", 15],       // Tuple: [EggID, Pal, Level]
    { EggID: "Egg_Fire_01", Level: 50 }  // Detailed Object
);

Tech: learnTech / forgetTech

Supports keys, raw IDs, and a magic "All" toggle that expands to every known technology.

await client.learnTech(id, "MegaShield");
await client.learnTech(id, "Altar", "GrapplingGun"); // Multiple args
await client.learnTech(id, "All"); // Grants every technology

Progression: giveProgression(id, options)

Cleanly grant experience or points using a standard object.

await client.giveProgression(id, { 
    exp: 5000, 
    technologyPoints: 10,
    lifmunks: 5 
});

API Reference

Info & Players

Method Alias Description
getVersion() version() Returns server and anticheat version info.
getPlayers() players() Returns a list of all players (online and offline).
getPlayer(id) player(id) Returns profile data (Supports PlayerUID/UserID).
findPlayerByName(name) — Exact name match helper.
findPlayersByPartialName(part) — Name fragment search helper.

Guilds & Bases

Method Alias Description
getGuilds() guilds() Returns a list of all guilds/groups.
getGuild(id) guild(id) Detailed guild info (Requires Guild GUID).
deleteBase(baseId) — Deletes a base camp (Requires Base GUID).

Deep-Dive

Method Alias Description
getPals(id) pals(id) Returns all Pals owned by player.
getItems(id) items(id) Returns player's full inventory.
getTechs(id) techs(id) Returns list of unlocked tech IDs.
getProgression(id) progression(id) Returns player stats and boss history.

Configuration

Option Default Description
token process.env.PD_TOKEN Your PalDefender Admin Token.
host 127.0.0.1 Server IP or Domain.
port 17993 REST API Port.
timeout 30000 Request timeout in ms.
displayAddress None Application name for API logs.

Error Handling

If the API returns a non-200 status, a PalDefenderApiError is thrown.

try {
    await client.giveItems("invalid-id", "Stone");
} catch (err) {
    if (err instanceof PalDefenderApiError) {
        console.error(`Status ${err.statusCode}: ${err.message}`);
    }
}