@wumx-labs/noxaeapi-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,548 @@
+interface RetryOptions {
+    /** Max number of attempts including the first one. Default 3. */
+    attempts?: number;
+    /** Base delay in ms used for exponential backoff. Default 300. */
+    baseDelayMs?: number;
+    /** Upper bound for any single backoff delay. Default 5000. */
+    maxDelayMs?: number;
+}
+interface NoxAeApiClientOptions {
+    /** Base URL of the server, e.g. "http://localhost:8080" or "https://mc.example.com". */
+    baseUrl: string;
+    /** The API key configured on the server (sent as the `key` header). */
+    apiKey?: string;
+    /** Request timeout in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Retry behavior for network errors, 429s, and 5xx responses. */
+    retry?: RetryOptions | false;
+    /** Extra headers sent on every request. */
+    headers?: Record<string, string>;
+    /** Override fetch, mainly for testing. Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+type QueryValue = string | number | boolean | null | undefined;
+declare class HttpEngine {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly timeoutMs;
+    private readonly retry;
+    private readonly extraHeaders;
+    private readonly fetchImpl;
+    constructor(options: NoxAeApiClientOptions);
+    private buildUrl;
+    request<T>(method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH", path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, QueryValue>;
+    }): Promise<T>;
+}
+
+interface OnlinePlayer {
+    uuid: string;
+    displayName: string;
+    address: string | null;
+    port: number | null;
+    exhaustion: number;
+    exp: number;
+    expLevel: number;
+    whitelisted: boolean;
+    banned: boolean;
+    op: boolean;
+    balance: number | null;
+    location: [number, number, number] | null;
+    dimension: string | null;
+    health: number;
+    hunger: number;
+    saturation: number;
+    gamemode: string;
+    lastPlayed: number;
+    authenticated: boolean | null;
+    registered: boolean | null;
+}
+interface OfflinePlayer {
+    uuid: string;
+    displayName: string;
+    whitelisted: boolean;
+    banned: boolean;
+    op: boolean;
+    balance: number | null;
+    lastPlayed: number;
+}
+interface ServerHealth {
+    cpus: number;
+    uptime: number;
+    totalMemory: number;
+    maxMemory: number;
+    freeMemory: number;
+}
+interface ServerBan {
+    target: string;
+    source: string | null;
+    reason: string | null;
+    expiration: string | null;
+}
+interface WhitelistEntry {
+    uuid: string;
+    name: string;
+}
+interface ServerInfo {
+    name: string;
+    motd: string;
+    version: string;
+    bukkitVersion: string;
+    tps: string;
+    health: ServerHealth;
+    bannedIps: ServerBan[];
+    bannedPlayers: ServerBan[];
+    whitelistedPlayers: WhitelistEntry[];
+    maxPlayers: number;
+    onlinePlayers: number;
+}
+interface World {
+    name: string;
+    uuid: string;
+    time: number;
+    storm: boolean;
+    thundering: boolean;
+    generateStructures: boolean;
+    allowAnimals: boolean;
+    allowMonsters: boolean;
+    difficulty: string;
+    environment: string;
+    seed: string;
+}
+interface Score {
+    entry: string;
+    value: number;
+}
+interface Objective {
+    name: string;
+    displayName: string;
+    criterion: string;
+    scores: Score[];
+    displaySlot: string | null;
+}
+interface Scoreboard {
+    objectives: string[];
+    entries: string[];
+}
+interface InventoryItem {
+    id: string;
+    count: number;
+    slot: number;
+}
+interface Plugin {
+    name: string;
+    enabled: boolean;
+    version: string;
+    website: string | null;
+    authors: string[];
+    depends: string[];
+    softDepends: string[];
+    apiVersion: string | null;
+    description: string | null;
+}
+interface EconomyInfo {
+    available: boolean;
+    [key: string]: unknown;
+}
+interface PlayerBalance {
+    uuid: string;
+    balance: number;
+}
+interface TopBalanceEntry {
+    uuid: string;
+    balance: number;
+}
+interface GroupInfo {
+    name: string;
+    permissions: string[];
+}
+interface PermissionNode {
+    permission: string;
+    value: boolean;
+    expiry: number;
+    server: string | null;
+    world: string | null;
+}
+interface Advancement {
+    key: string;
+    criteria: string[];
+}
+interface NoxAuthPlayerInfo {
+    uuid: string;
+    name: string;
+    registered: boolean;
+    authenticated: boolean;
+    lastIp: string | null;
+    lastLoginTime: number | null;
+    countryCode: string | null;
+    countryName: string | null;
+}
+interface PasswordCheckResult {
+    name: string;
+    valid: boolean;
+}
+interface PlayerStats {
+    uuid: string;
+    name: string;
+    kills: number;
+    deaths: number;
+    playtime: number;
+    blocksPlaced: number;
+    blocksBroken: number;
+}
+
+declare class PlayersModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** List currently online players. */
+    list(): Promise<OnlinePlayer[]>;
+    /** List all players the server has ever seen (online + offline). */
+    listAll(): Promise<OfflinePlayer[]>;
+    /** Get a single player by UUID (works for online or offline players). */
+    get(uuid: string): Promise<OnlinePlayer | OfflinePlayer>;
+    /** Get a player's inventory in a specific world. */
+    getInventory(playerUuid: string, worldUuid: string): Promise<InventoryItem[]>;
+    /** Kick an online player, optionally with a reason. */
+    kick(uuid: string, reason?: string): Promise<void>;
+    /** Ban a player, optionally with a reason and expiration. */
+    ban(uuid: string, reason?: string): Promise<void>;
+    /** Remove a player's ban. */
+    unban(uuid: string): Promise<void>;
+    /** Teleport a player to a location. */
+    teleport(uuid: string, location: {
+        x: number;
+        y: number;
+        z: number;
+        world?: string;
+    }): Promise<void>;
+    /** Change a player's gamemode. */
+    setGamemode(uuid: string, gamemode: "survival" | "creative" | "adventure" | "spectator"): Promise<void>;
+    /** Get kill/death/playtime/block stats for a player. */
+    getStats(uuid: string): Promise<PlayerStats>;
+}
+
+declare class EconomyModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Get info about the connected economy provider (Impactor on Fabric, Vault on Bukkit/Spigot/Paper). */
+    info(): Promise<EconomyInfo>;
+    /** Get a player's balance. */
+    getBalance(uuid: string): Promise<PlayerBalance>;
+    /** Get the top balances leaderboard. */
+    getTopBalance(limit?: number): Promise<TopBalanceEntry[]>;
+    /** Pay an amount to a player (adds to their balance). */
+    pay(uuid: string, amount: number): Promise<void>;
+    /** Debit an amount from a player (subtracts from their balance). */
+    debit(uuid: string, amount: number): Promise<void>;
+}
+
+declare class ServerModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Basic liveness check. */
+    ping(): Promise<{
+        status: string;
+    }>;
+    /** Get server info: version, MOTD, TPS, health, player counts, etc. */
+    info(): Promise<ServerInfo>;
+    /**
+     * Run a console command on the server.
+     * This is a privileged endpoint — requires a write-enabled API key.
+     */
+    exec(command: string): Promise<{
+        lines: string[];
+    }>;
+    /** List server operators. */
+    getOps(): Promise<WhitelistEntry[]>;
+    /** Grant operator status to a player. */
+    opPlayer(uuid: string): Promise<void>;
+    /** Revoke operator status from a player. */
+    deopPlayer(uuid: string): Promise<void>;
+    /** Get the current whitelist. */
+    getWhitelist(): Promise<WhitelistEntry[]>;
+    /** Add a player to the whitelist. */
+    addToWhitelist(uuid: string, name?: string): Promise<void>;
+    /** Remove a player from the whitelist. */
+    removeFromWhitelist(uuid: string): Promise<void>;
+    /**
+     * Restart the server.
+     * This is a privileged endpoint — requires a write-enabled API key.
+     */
+    restart(): Promise<void>;
+    /** Tail the server console log. */
+    getLogs(lines?: number): Promise<{
+        lines: string[];
+    }>;
+    /** Get entity counts on the server, optionally scoped to a world. */
+    getEntities(world?: string): Promise<{
+        world: string;
+        count: number;
+        entities: Record<string, number>;
+    }>;
+    /** Get loaded chunk counts, optionally scoped to a world. */
+    getChunks(world?: string): Promise<{
+        world: string;
+        loadedChunks: number;
+    }>;
+    /** Ban an IP address. */
+    banIp(ip: string, reason?: string): Promise<void>;
+    /** Get a scoreboard objective's scores by objective name. */
+    getObjective(name: string): Promise<unknown>;
+    /** List all scoreboard objectives and tracked entries. */
+    getScoreboard(): Promise<unknown>;
+    /** Set a score for an entry on an objective. */
+    setScore(objective: string, entry: string, value: number): Promise<void>;
+    /** Reset (remove) a score for an entry on an objective. */
+    resetScore(objective: string, entry: string): Promise<void>;
+    /** Broadcast a message to every player on the server. */
+    broadcast(message: string): Promise<void>;
+    /** Send a private message to a specific player. */
+    tell(uuid: string, message: string): Promise<void>;
+}
+
+declare class WorldsModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** List all worlds. */
+    list(): Promise<World[]>;
+    /** Save all worlds to disk. */
+    saveAll(): Promise<void>;
+    /** Get a download link/stream reference for all worlds. */
+    downloadAll(): Promise<{
+        url: string;
+    }>;
+    /** Get a single world by UUID. */
+    get(uuid: string): Promise<World>;
+    /** Save a specific world to disk. */
+    save(uuid: string): Promise<void>;
+    /** Get a download link/stream reference for a specific world. */
+    download(uuid: string): Promise<{
+        url: string;
+    }>;
+    /** Set the in-game time for a world. */
+    setTime(uuid: string, time: number): Promise<void>;
+    /** Set weather (storm/thundering) for a world. */
+    setWeather(uuid: string, weather: {
+        storm?: boolean;
+        thundering?: boolean;
+    }): Promise<void>;
+    /** Get entity counts within a specific world. */
+    getEntities(uuid: string): Promise<{
+        world: string;
+        count: number;
+        entities: Record<string, number>;
+    }>;
+}
+
+declare class PluginsModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** List all installed plugins/mods. */
+    list(): Promise<Plugin[]>;
+    /**
+     * Install a plugin from a URL or identifier.
+     * This is a privileged endpoint — requires a write-enabled API key.
+     */
+    install(source: string): Promise<void>;
+    /** Enable a plugin by name. */
+    enable(name: string): Promise<void>;
+    /** Disable a plugin by name. */
+    disable(name: string): Promise<void>;
+}
+
+declare class AdvancementsModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** List all advancements known to the server. */
+    list(): Promise<Advancement[]>;
+}
+declare class PlaceholdersModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /**
+     * Replace PlaceholderAPI-style placeholders (e.g. "%player_name%") for a
+     * player, returning the resolved string.
+     */
+    replace(uuid: string, text: string): Promise<{
+        result: string;
+    }>;
+}
+
+/**
+ * Wraps the `/v1/luckperms/*` routes. These only exist on the server when
+ * the LuckPerms mod is loaded — calling any method here against a server
+ * without it will fail (typically a 404). There's no separate "is this
+ * available" flag from the SDK's side; check `client.plugins.list()` for
+ * LuckPerms if you need to branch on it ahead of time.
+ */
+declare class LuckPermsModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Get the groups a player belongs to. */
+    getPlayerGroups(uuid: string): Promise<string[]>;
+    /** Get a player's effective permission nodes. */
+    getPlayerPermissions(uuid: string): Promise<PermissionNode[]>;
+    /** Add a permission node to a player. */
+    addPlayerPermission(uuid: string, permission: string, value?: boolean): Promise<void>;
+    /** Check whether a player has a given permission. */
+    checkPlayerPermission(uuid: string, permission: string): Promise<{
+        permission: string;
+        value: boolean;
+    }>;
+    /** Remove a permission node from a player. */
+    removePlayerPermission(uuid: string, permission: string): Promise<void>;
+    /** Set a player's primary group. */
+    setPlayerGroup(uuid: string, group: string): Promise<void>;
+    /** Remove a group from a player. */
+    removePlayerGroup(uuid: string, groupName: string): Promise<void>;
+    /** List all known groups. */
+    getGroups(): Promise<string[]>;
+    /** Get the permissions attached to a specific group. */
+    getGroupPermissions(name: string): Promise<GroupInfo>;
+}
+
+/**
+ * Wraps the `/v1/noxauth/*` routes. These only work when `noxauth.enabled`
+ * is set to true in the server's noxaeapi-config.yml and the NoxAuth plugin
+ * is installed.
+ */
+declare class NoxAuthModule {
+    private readonly http;
+    constructor(http: HttpEngine);
+    /** Get NoxAuth registration/auth info for a player by name. */
+    getPlayerAuth(name: string): Promise<NoxAuthPlayerInfo>;
+    /** Check whether a password matches a player's stored NoxAuth password. */
+    checkPassword(name: string, password: string): Promise<PasswordCheckResult>;
+}
+
+type NoxAeApiWsEvent = "open" | "close" | "error" | "console" | "event" | "message";
+type Listener = (payload: unknown) => void;
+interface NoxAeApiWsOptions {
+    /** Base URL of the server, same one passed to the client (http/https). */
+    baseUrl: string;
+    apiKey?: string;
+    /** Route suffix under the websocket base, e.g. "console" or "events". Default "events". */
+    route?: string;
+    /** Whether to auto-reconnect on unexpected close. Default true. */
+    autoReconnect?: boolean;
+    /** Max reconnect delay in ms. Default 30000. */
+    maxReconnectDelayMs?: number;
+    /** Override the WebSocket implementation, mainly for testing / non-browser runtimes. */
+    webSocketImpl?: typeof WebSocket;
+}
+/**
+ * Thin wrapper around the server's WebSocket endpoints (console tail and
+ * event broadcasts). Handles reconnection with exponential backoff so
+ * consumers can just attach listeners and not think about the socket
+ * lifecycle.
+ *
+ * Usage:
+ * ```ts
+ * const ws = client.connect({ route: "console" });
+ * ws.on("console", (line) => console.log(line));
+ * ws.on("close", () => console.log("disconnected"));
+ * ```
+ */
+declare class NoxAeApiSocket {
+    private readonly options;
+    private socket;
+    private readonly listeners;
+    private reconnectAttempt;
+    private closedByUser;
+    private readonly wsImpl;
+    constructor(options: NoxAeApiWsOptions);
+    private open;
+    private scheduleReconnect;
+    on(event: NoxAeApiWsEvent, listener: Listener): () => void;
+    off(event: NoxAeApiWsEvent, listener: Listener): void;
+    private emit;
+    /** Send a raw payload over the socket, JSON-stringified if not already a string. */
+    send(payload: unknown): void;
+    /** Close the socket and stop reconnecting. */
+    close(): void;
+}
+
+declare class NoxAeApiClient {
+    readonly players: PlayersModule;
+    readonly economy: EconomyModule;
+    readonly server: ServerModule;
+    readonly worlds: WorldsModule;
+    readonly plugins: PluginsModule;
+    readonly advancements: AdvancementsModule;
+    readonly placeholders: PlaceholdersModule;
+    /** Only works if LuckPerms is loaded on the target server. */
+    readonly luckperms: LuckPermsModule;
+    /** Only works if `noxauth.enabled: true` is set in the server config. */
+    readonly noxauth: NoxAuthModule;
+    private readonly http;
+    private readonly baseUrl;
+    private readonly apiKey?;
+    constructor(options: NoxAeApiClientOptions);
+    /**
+     * Build a client from environment variables:
+     * `NOXAEAPI_BASE_URL` and `NOXAEAPI_KEY`.
+     *
+     * This is a convenience for Node-like runtimes; the SDK itself never
+     * reads `process.env` implicitly outside of this method, and does not
+     * load `.env` files — use a library like `dotenv` in your own app if
+     * you want that, then call `NoxAeApiClient.fromEnv()` after it's loaded.
+     */
+    static fromEnv(overrides?: Partial<NoxAeApiClientOptions>): NoxAeApiClient;
+    /** Open a WebSocket connection to the server (console tail or event stream). */
+    connect(options?: Partial<NoxAeApiWsOptions>): NoxAeApiSocket;
+}
+
+interface NoxAeApiErrorInfo {
+    status: number;
+    method: string;
+    path: string;
+    body?: unknown;
+}
+/**
+ * Base error thrown for any non-2xx response from a NoxAeApi server.
+ * Prefer catching the more specific subclasses below when you need to
+ * branch on the failure reason.
+ */
+declare class NoxAeApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body?: unknown;
+    constructor(message: string, info: NoxAeApiErrorInfo);
+}
+/** 401 — the API key is missing or not recognized by the server. */
+declare class NoxAeApiUnauthorizedError extends NoxAeApiError {
+    constructor(info: NoxAeApiErrorInfo);
+}
+/**
+ * 403 — the API key is valid but isn't allowed to call this endpoint
+ * (read-only key hitting a write route, or an endpoint restriction set
+ * on the key). This is a server-side permission decision; the SDK does
+ * not attempt to predict or enforce it client-side.
+ */
+declare class NoxAeApiForbiddenError extends NoxAeApiError {
+    constructor(info: NoxAeApiErrorInfo);
+}
+/** 404 — the target resource (player, world, plugin, etc.) wasn't found. */
+declare class NoxAeApiNotFoundError extends NoxAeApiError {
+    constructor(info: NoxAeApiErrorInfo);
+}
+/** 429 — rate limited. `retryAfterMs` is populated when the server sends a Retry-After header. */
+declare class NoxAeApiRateLimitError extends NoxAeApiError {
+    readonly retryAfterMs?: number;
+    constructor(info: NoxAeApiErrorInfo, retryAfterMs?: number);
+}
+/** 5xx — the server errored out. Usually safe to retry. */
+declare class NoxAeApiServerError extends NoxAeApiError {
+    constructor(info: NoxAeApiErrorInfo);
+}
+/** The request could not complete at all (DNS, connection refused, timeout, abort). */
+declare class NoxAeApiNetworkError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly cause?: unknown;
+    constructor(message: string, method: string, path: string, cause?: unknown);
+}
+
+export { type Advancement, type EconomyInfo, type GroupInfo, type InventoryItem, NoxAeApiClient, type NoxAeApiClientOptions, NoxAeApiError, NoxAeApiForbiddenError, NoxAeApiNetworkError, NoxAeApiNotFoundError, NoxAeApiRateLimitError, NoxAeApiServerError, NoxAeApiSocket, NoxAeApiUnauthorizedError, type NoxAeApiWsEvent, type NoxAeApiWsOptions, type NoxAuthPlayerInfo, type Objective, type OfflinePlayer, type OnlinePlayer, type PasswordCheckResult, type PermissionNode, type PlayerBalance, type PlayerStats, type Plugin, type RetryOptions, type Score, type Scoreboard, type ServerBan, type ServerHealth, type ServerInfo, type TopBalanceEntry, type WhitelistEntry, type World };