@nethergames/api v2.8.2

@nethergames/api

Fully typed client for the NetherGames API. This package requires ESM.

Install

npm install @nethergames/api

Usage

import {NetherGamesClient} from '@nethergames/api'

const ng = new NetherGamesClient(process.env.NG_API_KEY)
const player = await ng.players.retrieve('Hampus3770')
const guild = await ng.guilds.retrieve(player.guild)

API

new NetherGamesClient(apiKey?, options?)

Returns a new instance.

options

Type: object

baseUrl

Type: string\ Default: https://api.ngmc.co

API host to use when sending requests.

cacheMaxSize

Type: number\ Default: 1000

The maximum amount of LRU objects to hold in memory.

userAgent

Type: string\ Default: NetherGames-API-Client/2.8.2

User-agent to use when sending requests.

userAgentAppendix

Optional\ Type: string

Append an identifier to the user agent in parentheses.\ A unique identifier allows us to identify requests in our error monitoring tools.\ Example: Casper's Discord Bot => NetherGames-API-Client/2.8.2 (Casper's Discord Bot)

Instance

All resource methods return a Promise, so you must await them.

.announcements

Returns an AnnouncementsResource.

.factions

Returns a FactionsResource.

.guilds

Returns a GuildsResource.

.leaderboard

Returns a LeaderboardResource.

.players

Returns a PlayersResource.

.search

Returns a SearchResource.

.servers

Returns a ServersResource.

.status

Returns a StatusResource.

.stream

Returns a StreamResource.

.updates

Returns an UpdatesResource.

.lastBuildId

Type: string\ Default: null

The build ID returned from the previous request.

.lastRateLimit

Type: object\ Default: null

The rate limit returned from the previous request.

.lastServerMeta

Type: object\ Default: null

Stores the last retrieved server metadata object. Useful for caching at startup.

.on(event, callback)

Event emitter for error, request, and response. Useful for debugging.

Announcements

.list(type, limit?) Docs

List announcements for a specified type and an optional limit.

Factions

.retrieve(faction, params?) Docs

Retrieve a faction by name or null if not found.

.search(faction[], params?) Docs

Find many (1-100) factions at once.

.list(params?) Docs

A paginated list of factions.

.check(faction) Docs

Check if the specified faction name or ID exists.

Guilds

.retrieve(guild, params?) Docs

Retrieve a guild by name, or null if not found.

.search(guild[], params?) Docs

Find many (1-100) guilds at once.

.list(params?) Docs

A paginated list of guilds.

.check(guild) Docs

Check if the specified guild name or ID exists.

Leaderboard

.list(type, params?) Docs

Return the leaderboard for a specified type with optional params.

.bulk(query[]) Docs

Find many (1-100) leaderboards at once.

Players

.retrieve(player, params?) Docs

Retrieve a player by name or null if not found.

.search(player[], params?) Docs

Find many (1-100) players at once.

.list(params?) Docs

A paginated list of players.

.leaderboard(player, params?) Docs

Retrieve a player leaderboard, or null if not found.

.leaderboardBulk(player[], params?) Docs

Find many (1-100) player leaderboards at once.

.stats(player, type) Docs

Retrieve a player's stats for a specified type.

.statsHistory(player, params?) Docs

Retrieve hourly player stats history. API key required to request new players.

.statsHistoryBulk(players, params?) Docs

Retrieve hourly player stats history in bulk. API key required to request new players.

.xuidMapping(xuidOrUsername[]) Docs

Get a key-value mapping of XUIDs to usernames or vice versa.

.punishments(player) Docs

Retrieve a player's punishments.

.check(player) Docs

Check if a player by the specified username or XUID exists.

Search

.simple(name) Docs

Performs a "simple" search, returning exact matches for player, guild, and faction.

.fulltext(query, params?) Docs

Performs a "fulltext" search, returning partial name matches for the query for all types.

Servers

.retrieve() Docs

Retrieve server statistics.

.meta() Docs

Retrieve server metadata.

.ping(ip = 'play.nethergames.org', port = 19132) Docs

Retrieve server data for any *.nethergames.org IP or null if not found.

.playerCount() Docs

Retrieve the total player count (cached for one hour).

Status

.retrieve() Docs

Retrieve service status.

Stream

.retrieve() Docs

Retrieve YouTube streaming status.

Updates

.list(params?) Docs

List server updates.