bgg-ts-client

bgg-ts-client

A TypeScript client for the official BoardGameGeek XML API v2.

Note: This project is a fork of boardgamegeekclient by learningprocesss. It is now developed and maintained independently.

Key features

• :ballot_box_with_check: Support Authorization via BGG tokens
• :ballot_box_with_check: Fully typed requests and responses
• :ballot_box_with_check: Easy to use
• :ballot_box_with_check: Typescript written
• :ballot_box_with_check: Promisified
• :ballot_box_with_check: thing, family, forum, thread, user, guild, play, collection endpoints
• :ballot_box_with_check: Structured error handling with typed error classes

Prerequisites

Starting in Fall 2025, BoardGameGeek requires all API clients to use authorization. Before using this package, you must register your application on BoardGameGeek and obtain an access token.

Register and manage your application here: https://boardgamegeek.com/applications

Installation

npm i bgg-ts-client

yarn add bgg-ts-client

Usage

In Node.js (commonjs) environment

const { BggClient } = require("bgg-ts-client");

In ES environment

import { BggClient } from 'bgg-ts-client';

Initialize BggClient and get singleton instance

const client = BggClient.Create({ apiKey: 'YOUR_API_KEY' });

API

Interact with boardgamegeek entities using the corresponding client object and fire a request with query or queryWithProgress method.

Thing

Get boardgame, boardgame expansion, boardgame accessory, videogame, rpgitem, rpgissue information. Thing client exposes query and queryWithProgress.

Examples

const things: BggThingDto[] = await client.thing.query({ id: [174430, 35421],
                                                         videos: 1,
                                                         comments: 1,
                                                         marketplace: 1,
                                                         stats: 1,
                                                         type: "boardgame" });

// with progress handler as parameter

await client.thing.queryWithProgress({
                id: [250621, 257668, 226255, 340790, 279307, 279306, 345121, 271447, 187104, 253618, 271512, 432, 68448, 173346, 346703, 302260, 239472, 172818, 231398, 202408, 267814, 267813, 191189, 267127, 281946, 264647, 2272, 230085, 31260, 247367, 256442, 161970, 6249, 181293],
                videos: 1,
                comments: 1,
                marketplace: 1,
                stats: 1,
                type: "boardgame"
            }, { limit: 10 }, _data => {

            });

// with progress handler registered on the client itself

client.thing.progressHandler = (_data) => { };

await client.thing.queryWithProgress({
    id: [250621, 257668, 226255, 340790, 279307, 279306, 345121, 271447, 187104, 253618, 271512, 432, 68448, 173346, 346703, 302260, 239472, 172818, 231398, 202408, 267814, 267813, 191189, 267127, 281946, 264647, 2272, 230085, 31260, 247367, 256442, 161970, 6249, 181293],
    videos: 1,
    comments: 1,
    marketplace: 1,
    stats: 1,
    type: "boardgame"
}, { limit: 10 });

Family

Get rpg, rpgperiodical, boardgamefamily information. Family client exposes query and queryWithProgress.

Examples

const families = await client.family.query({ id: [174430, 35421] });

Forum List

Get a list of forums (in boardgame or family page (of the id), forums tab, left sidebars with all forums). ForumList client exposes query and queryWithProgress.

Examples

const forumlists: BggForumlistDto[] = await client.forumlist.query({ id: [8374,22184,59218,1029,2076], type: ['family']});

Forum

Get a single forum.

Examples

const forum = await client.forum.query({ id: 19, page: 3 });

Thread

Get a single thread.

Examples

const threads: BggThreadDto[] = await client.thread.query({ id: 2571698, minarticledate: '2021-01-03', count: 15 });

User

Get public profile information about a user by username.

Examples

const users: BggUserDto[] = await client.user.query({ name: 'mattiabanned', hot: 1, top: 1 });

Guild

Get a single guild.

Examples

const guilds: BggGuildDto[] = await client.guild.query({ id: 1000, members: 1, sort: 'date', page: 1 });

Play

Request plays logged by a particular user or for a particular item.

Examples

const plays: BggPlayDto[] = await client.play.query({ username: 'mattiabanned' });

Collection

Request the collection of a particular user.

Examples

const collections: BggCollectionDto[]  = await client.collection.query({ username: 'mattiabanned', excludesubtype: ["boardgameaccessory"] });

Error Handling

All errors thrown by the client are wrapped in a BggClientError, which includes the endpoint name and the underlying cause. You can inspect the cause to determine whether the failure was an HTTP error or a parse error.

• BggClientError — wraps all errors; includes endpoint and cause
• BggApiError — HTTP failures; includes statusCode and url
• BggParseError — XML/DTO parse failures; includes truncated rawData

import { BggClient, BggClientError, BggApiError, BggParseError } from 'bgg-ts-client';

const client = BggClient.Create({ apiKey: 'YOUR_API_KEY' });

try {
  const things = await client.thing.query({ id: [174430], type: 'boardgame' });
} catch (error) {
  if (error instanceof BggClientError) {
    console.log(error.endpoint); // e.g. "thing"

    if (error.cause instanceof BggApiError) {
      console.log(error.cause.statusCode); // e.g. 500
      console.log(error.cause.url);
    }

    if (error.cause instanceof BggParseError) {
      console.log(error.cause.rawData); // truncated to 500 chars
    }
  }
}