bgg-xml-api-client/dist/index.d.ts

A client for Boardgamegeek.com XML API (v1 and v2) that returns data as JS object.

type BggCollectionSubtype = 'boardgame' | 'boardgameexpansion' | 'boardgameaccessory' | 'rpgitem' | 'rpgissue' | 'videogame';
type ZeroOrOne = 0 | 1;
interface BggCollectionParams {
    username: string;
    version?: OneOrNothing;
    subtype?: BggCollectionSubtype;
    excludesubtype?: BggCollectionSubtype;
    id?: number | number[] | string;
    brief?: OneOrNothing;
    stats?: OneOrNothing;
    own?: ZeroOrOne;
    rated?: ZeroOrOne;
    played?: ZeroOrOne;
    comment?: ZeroOrOne;
    trade?: ZeroOrOne;
    want?: ZeroOrOne;
    wishlist?: ZeroOrOne;
    wishlistpriority?: 1 | 2 | 3 | 4 | 5;
    preordered?: ZeroOrOne;
    wanttoplay?: ZeroOrOne;
    wanttobuy?: ZeroOrOne;
    prevowned?: ZeroOrOne;
    hasparts?: ZeroOrOne;
    wantparts?: ZeroOrOne;
    minrating?: number;
    rating?: number;
    minbggrating?: number;
    bggrating?: number;
    minplays?: number;
    maxplays?: number;
    showprivate?: OneOrNothing;
    collid?: number;
    modifiedsince?: string;
}
interface BggCollectionResponse {
    item: {
        name: {
            text: string;
            sortindex: number;
        };
        originalname: string;
        yearpublished: number;
        image: string;
        thumbnail: string;
        stats: {
            rating: {
                usersrated: OfValue<number>;
                average: OfValue<number>;
                bayesaverage: OfValue<number>;
                stddev: OfValue<number>;
                median: OfValue<number>;
                ranks: {
                    rank: {
                        type: 'subtype' | 'family' | string;
                        id: number;
                        name: string;
                        friendlyname: string;
                        value: number;
                        bayesaverage: number;
                    }[];
                };
                value: string;
            };
            minplayers: 2;
            maxplayers: 2;
            minplaytime: 150;
            maxplaytime: 150;
            playingtime: 150;
            numowned: 4434;
        };
        status: {
            own: ZeroOrOne;
            prevowned: ZeroOrOne;
            fortrade: ZeroOrOne;
            want: ZeroOrOne;
            wanttoplay: ZeroOrOne;
            wanttobuy: ZeroOrOne;
            wishlist: ZeroOrOne;
            wishlistpriority?: 1 | 2 | 3 | 4 | 5;
            preordered: ZeroOrOne;
            lastmodified: string;
        };
        numplays: number;
        version?: {
            item: {
                thumbnail: string;
                image: string;
                link: {
                    type: 'boardgameversion' | 'boardgamepublisher' | 'language' | string;
                    id: number;
                    value: string;
                    inbound?: boolean;
                }[];
                name: {
                    type: 'primary' | string;
                    sortindex: number;
                    value: string;
                };
                yearpublished: OfValue<number>;
                productcode: OfValue<string>;
                width: OfValue<number>;
                length: OfValue<number>;
                depth: OfValue<number>;
                weight: OfValue<number>;
                type: 'boardgameversion' | string;
                id: number;
            };
        };
        objecttype: 'thing' | string;
        objectid: number;
        subtype: string;
        collid: number;
    }[];
    totalitems: number;
    termsofuse: string;
    pubdate: string;
    [prop: string]: unknown;
}
declare function getBggCollection(params: BggCollectionParams, settings?: Partial<ClientOptions>): Promise<BggCollectionResponse>;

interface BggFamilyParams {
    id?: number | number[] | string;
    type?: BggFamilyType;
}
interface NewType {
    type: 'primary' | string;
    sortindex: number;
    value: string;
}
interface BggFamilyResponse {
    item: SingleOrMany<{
        thumbnail: string;
        image: string;
        name: NewType;
        description: string;
        link: {
            type: 'boardgamefamily' | string;
            id: number;
            value: string;
            inbound: boolean;
        }[];
        type: 'boardgamefamily' | string;
        [prop: string]: unknown;
    }>;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggFamily(params: BggFamilyParams, settings?: Partial<ClientOptions>): Promise<BggFamilyResponse>;

interface BggForumParams {
    id?: number;
    page?: number;
}
interface BggForumResponse {
    threads: {
        thread: {
            id: number;
            subject: string;
            author: string;
            numarticles: number;
            postdate: string;
            lastpostdate: string;
            [prop: string]: unknown;
        }[];
        [prop: string]: unknown;
    };
    id: number;
    title: string;
    numthreads: number;
    numposts: number;
    lastpostdate: string;
    noposting: number;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggForum(params: BggForumParams, settings?: Partial<ClientOptions>): Promise<BggForumResponse>;

interface BggForumlistParams {
    id?: number;
    type?: 'thing' | 'family';
}
interface BggForumlistResponse {
    [prop: string]: unknown;
}
declare function getBggForumlist(params: BggForumlistParams, settings?: Partial<ClientOptions>): Promise<BggForumlistResponse>;

interface GeeklistParams {
    id: number;
    comments?: OneOrNothing;
}
interface GeeklistItemComment {
    text: string;
    username: string;
    date: string;
    postdate: string;
    editdate: string;
    thumbs: number;
    [prop: string]: unknown;
}
interface GeeklistResponse {
    postdate: string;
    postdate_timestamp: number;
    editdate: string;
    editdate_timestamp: number;
    thumbs: number;
    numitems: number;
    username: string;
    title: string;
    description: string;
    item: {
        body: string;
        comment: GeeklistItemComment | GeeklistItemComment[];
        id: number;
        objecttype: 'thing' | string;
        subtype: 'boardgame' | 'boardgameaccessory' | string;
        objectid: number;
        objectname: string;
        username: string;
        postdate: string;
        editdate: string;
        thumbs: number;
        imageid: number;
        [prop: string]: unknown;
    }[];
    id: number;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggGeeklist(params: GeeklistParams, settings?: Partial<ClientOptions>): Promise<GeeklistResponse>;

interface BggGuildParams {
    id?: number;
    members?: OneOrNothing;
    sort?: 'username' | 'date';
    page?: number;
}
interface BggGuildResponse {
    category: string;
    website: string;
    manager: string;
    description: string;
    location: {
        addr1: string;
        addr2: string;
        city: string;
        stateorprovince: string;
        postalcode: string;
        country: string;
        [prop: string]: unknown;
    };
    members: {
        member: {
            name: string;
            date: string;
            [prop: string]: unknown;
        }[];
        count: number;
        page: number;
    };
    id: number;
    name: string;
    created: string;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggGuild(params: BggGuildParams, settings?: Partial<ClientOptions>): Promise<BggGuildResponse>;

interface BggHotParams {
    type: 'boardgame' | 'rpg' | 'videogame' | 'boardgameperson' | 'rpgperson' | 'boardgamecompany' | 'rpgcompany' | 'videogamecompany';
}
interface BggHotResponse {
    item: {
        thumbnail: OfValue<string>;
        name: OfValue<string>;
        yearpublished?: OfValue<number>;
        id: number;
        rank: number;
        [prop: string]: unknown;
    }[];
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggHot(params: BggHotParams, settings?: Partial<ClientOptions>): Promise<BggHotResponse>;

interface BggPlaysParams {
    username?: string;
    id?: number;
    type?: 'thing' | 'family';
    mindate?: string;
    maxdate?: string;
    subtype?: 'boardgame' | 'boardgameexpansion' | 'boardgameaccessory' | 'rpgitem' | 'videogame';
    page?: number;
}
interface BggPlaysResponse {
    play: {
        item: {
            subtypes: {
                subtype: OfValue<string> | OfValue<string>[];
            };
            name: string;
            objecttype: 'thing' | string;
            objectid: number;
            [prop: string]: unknown;
        };
        id: number;
        date: string;
        quantity: number;
        length: number;
        incomplete: number;
        nowinstats: number;
        location: string;
        [prop: string]: unknown;
    }[];
    username: string;
    userid: number;
    total: number;
    page: number;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggPlays(params: BggPlaysParams, settings?: Partial<ClientOptions>): Promise<BggPlaysResponse>;

type SearchType = 'rpgitem' | 'videogame' | 'boardgame' | 'boardgameaccessory' | 'boardgameexpansion';
interface BggSearchParams {
    query: string;
    type?: SearchType | SearchType[] | string;
    exact?: OneOrNothing;
}
interface BggSearchResponse {
    item: {
        name: {
            type: 'primary' | string;
            value: string;
        };
        yearpublished?: OfValue<number>;
        type: 'boardgame' | 'boardgameexpansion' | 'rpgitem' | 'videogame' | string;
        id: number;
        [prop: string]: unknown;
    }[];
    total: number;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggSearch(params: BggSearchParams, settings?: Partial<ClientOptions>): Promise<BggSearchResponse>;

interface BggThingParams {
    id?: number | number[] | string;
    type?: ThingType | ThingType[] | string;
    versions?: OneOrNothing;
    videos?: OneOrNothing;
    stats?: OneOrNothing;
    historical?: OneOrNothing;
    marketplace?: OneOrNothing;
    comments?: OneOrNothing;
    ratingcomments?: OneOrNothing;
    page?: number;
    pagesize?: number;
}
type BggThingLinkType = 'boardgamecategory' | 'boardgamemechanic' | 'boardgamefamily' | 'boardgameexpansion' | 'boardgameaccessory' | 'boardgamecompilation' | 'boardgameimplementation' | 'boardgamedesigner' | 'boardgameartist' | 'boardgamepublisher' | string;
type BggVideogameLinkType = 'videogameplatform' | 'videogamegenre' | 'videogametheme' | 'videogamefranchise' | 'videogameseries' | 'videogamemode' | 'videogamedeveloper' | 'videogamepublisher' | string;
type BggRpgitemLinkType = 'rpg' | 'rpggenre' | 'rpgcategory' | 'rpgmechanic' | 'rpgpublisher' | 'rpgdesigner' | 'rpgartist' | 'rpgproducer' | string;
interface BggThingName {
    type: 'primary' | 'alternate' | string;
    sortindex: number;
    value: string;
}
interface BggThingLink<T = BggThingLinkType> {
    type: T;
    id: number;
    value: string;
    [prop: string]: unknown;
}
interface BggThingVideo {
    id: number;
    title: string;
    category: 'instructional' | 'unboxing' | 'review' | 'humor' | 'session' | 'interview' | 'other' | string;
    language: string;
    link: string;
    username: string;
    userid: number;
    postdate: string;
    [prop: string]: unknown;
}
interface BggThingMarketplaceListing {
    listdate: OfValue<string>;
    price: {
        currency: string;
        value: number;
    };
    condition: OfValue<string>;
    notes: OfValue<string>;
    link: {
        href: string;
        title: string;
    };
    [prop: string]: unknown;
}
interface BggThingItemBase {
    thumbnail: string;
    image: string;
    name: SingleOrMany<BggThingName>;
    description: string;
    videos?: {
        video: SingleOrMany<BggThingVideo>;
        total: number;
    };
    comments?: {
        comment: SingleOrMany<{
            username: string;
            rating: 'N/A' | number;
            value: string;
            [prop: string]: unknown;
        }>;
        page: number;
        totalitems: number;
    };
}
interface BggBoardgameItem extends BggThingItemBase {
    yearpublished: OfValue<number>;
    minplayers: OfValue<number>;
    maxplayers: OfValue<number>;
    poll: SingleOrMany<{
        [prop: string]: unknown;
    }>;
    playingtime: OfValue<number>;
    minplaytime: OfValue<number>;
    maxplaytime: OfValue<number>;
    minage: OfValue<number>;
    link: SingleOrMany<BggThingLink>;
    versions?: {
        item: SingleOrMany<{
            thumbnail: string;
            image: string;
            link: SingleOrMany<BggThingLink>;
            name: SingleOrMany<BggThingName>;
            yearpublished: OfValue<number>;
            productcode: OfValue<string>;
            width: OfValue<number>;
            length: OfValue<number>;
            depth: OfValue<number>;
            weight: OfValue<number>;
            type: 'boardgameversion' | string;
            id: number;
            [prop: string]: unknown;
        }>;
    };
    marketplacelistings?: {
        listing: SingleOrMany<BggThingMarketplaceListing>;
    };
    statistics?: {
        ratings: {
            usersrated: OfValue<number>;
            average: OfValue<number>;
            bayesaverage: OfValue<number>;
            ranks: {
                rank: SingleOrMany<{
                    type: 'subtype' | 'family' | string;
                    id: number;
                    name: string;
                    friendlyname: string;
                    value: number;
                    bayesaverage: number;
                    [prop: string]: unknown;
                }>;
            };
            stddev: OfValue<number>;
            median: OfValue<number>;
            owned: OfValue<number>;
            trading: OfValue<number>;
            wanting: OfValue<number>;
            wishing: OfValue<number>;
            numcomments: OfValue<number>;
            numweights: OfValue<number>;
            averageweight: OfValue<number>;
            [prop: string]: unknown;
        };
        page: number;
    };
    type: 'boardgame';
    id: number;
    [prop: string]: unknown;
}
type BggBoardgameexpansionItem = BggBoardgameItem & {
    type: 'boardgameexpansion';
};
interface BggBoardgameaccessoryItem extends BggThingItemBase {
    yearpublished: OfValue<number>;
    link: SingleOrMany<BggThingLink>;
    versions?: {
        item: SingleOrMany<{
            thumbnail?: string;
            image?: string;
            type: 'bgaccessoryversion' | string;
            id: number;
            [prop: string]: unknown;
        }>;
    };
    marketplacelistings?: {
        listing: SingleOrMany<BggThingMarketplaceListing>;
    };
    type: 'boardgameaccessory';
    id: number;
    [prop: string]: unknown;
}
interface BggVideogameItem extends BggThingItemBase {
    link: SingleOrMany<BggThingLink<BggVideogameLinkType>>;
    minplayers: OfValue<number>;
    maxplayers: OfValue<number>;
    releasedate: OfValue<string>;
    versions?: {
        item: SingleOrMany<{
            type: 'vgcharacterversion' | 'videogameversion' | string;
            id: number;
            thumbnail?: string;
            image?: string;
            link?: SingleOrMany<BggThingLink<BggVideogameLinkType>>;
            name?: SingleOrMany<BggThingName>;
            releasedate?: OfValue<string>;
            [prop: string]: unknown;
        }>;
    };
    type: 'videogame';
    id: number;
    [prop: string]: unknown;
}
interface BggRpgitemItem extends BggThingItemBase {
    link: SingleOrMany<BggThingLink<BggRpgitemLinkType>>;
    yearpublished: OfValue<number>;
    seriescode: OfValue<string>;
    versions?: {
        item: SingleOrMany<{
            thumbnail?: string;
            image?: string;
            name?: SingleOrMany<BggThingName>;
            yearpublished?: OfValue<number>;
            format: OfValue<'electronic' | 'hardcover' | string>;
            link?: SingleOrMany<{
                type: string;
                id: number;
                value: string;
                [prop: string]: unknown;
            }>;
            productcode: OfValue<string>;
            pagecount: OfValue<number>;
            isbn10: OfValue<string>;
            isbn13: OfValue<string>;
            width: OfValue<number>;
            height: OfValue<number>;
            weight: OfValue<number>;
            description: string;
            type: 'rpgitemversion';
            id: number;
        }>;
    };
    marketplacelistings?: {
        listing: SingleOrMany<BggThingMarketplaceListing>;
    };
    type: 'rpgitem';
    id: number;
    [prop: string]: unknown;
}
interface BggThingResponse {
    item: SingleOrMany<BggBoardgameItem | BggBoardgameexpansionItem | BggBoardgameaccessoryItem | BggVideogameItem | BggRpgitemItem | unknown>;
    termsofuse: string;
    [prop: string]: unknown;
}
declare function getBggThing(params: BggThingParams, settings?: Partial<ClientOptions>): Promise<BggThingResponse>;

interface BggThreadParams {
    id?: number;
    minarticleid?: number;
    minarticledate?: string;
    count?: number;
}
interface BggThreadResponse {
    [prop: string]: unknown;
}
declare function getBggThread(params: BggThreadParams, settings?: Partial<ClientOptions>): Promise<BggThreadResponse>;

interface BggUserParams {
    name?: string;
    buddies?: OneOrNothing;
    guilds?: OneOrNothing;
    hot?: OneOrNothing;
    top?: OneOrNothing;
    domain?: 'boardgame' | 'rpg' | 'videogame';
    page?: number;
}
interface BggUserResponse {
    firstname: OfValue<string>;
    lastname: OfValue<string>;
    avatarlink: OfValue<string>;
    yearregistered: OfValue<number>;
    lastlogin: OfValue<string>;
    stateorprovince: OfValue<string>;
    country: OfValue<string>;
    webaddress: OfValue<string>;
    xboxaccount: OfValue<string>;
    wiiaccount: OfValue<string>;
    psnaccount: OfValue<string>;
    battlenetaccount: OfValue<string>;
    steamaccount: OfValue<string>;
    traderating: OfValue<number>;
    id: number;
    name: string;
    termsofuse: string;
    buddies?: {
        buddy: {
            id: number;
            name: string;
        }[];
        total: number;
        page: number;
    };
    guilds: {
        total: number;
        page: number;
    };
    [key: string]: any;
}
declare function getBggUser(params: BggUserParams, settings?: Partial<ClientOptions>): Promise<BggUserResponse>;

type ResourceName = 'geeklist' | 'thing' | 'family' | 'forumlist' | 'forum' | 'thread' | 'user' | 'guild' | 'plays' | 'collection' | 'hot' | 'search';
interface ClientOptions {
    maxRetries: number;
    retryInterval: number;
    timeout: number;
}
type OneOrNothing = 1 | undefined;
type SingleOrMany<T> = T | T[];
interface OfValue<T = any> {
    value: T;
}
type ThingType = 'boardgame' | 'boardgameexpansion' | 'boardgameaccessory' | 'videogame' | 'rpgitem' | 'rpgissue';
type BggFamilyType = 'rpg' | 'rpgperiodical' | 'boardgamefamily';
type BggParams = BggCollectionParams | BggFamilyParams | BggForumParams | BggForumlistParams | GeeklistParams | BggGuildParams | BggHotParams | BggPlaysParams | BggSearchParams | BggThingParams | BggThreadParams | BggUserParams;
type XmlString = string;
interface XmlParser {
    parse: <T = unknown>(text: XmlString) => T;
}

declare const bggXmlApiClient: {
    get: <T = unknown>(resource: ResourceName, queryParams: BggParams, { maxRetries, retryInterval, timeout, }?: Partial<ClientOptions>) => Promise<T>;
};

export { type BggBoardgameItem, type BggBoardgameaccessoryItem, type BggBoardgameexpansionItem, type BggCollectionParams, type BggCollectionResponse, type BggFamilyParams, type BggFamilyResponse, type BggFamilyType, type BggForumParams, type BggForumResponse, type BggForumlistParams, type BggForumlistResponse, type BggGuildParams, type BggGuildResponse, type BggHotParams, type BggHotResponse, type BggParams, type BggPlaysParams, type BggPlaysResponse, type BggRpgitemItem, type BggRpgitemLinkType, type BggSearchParams, type BggSearchResponse, type BggThingItemBase, type BggThingLink, type BggThingLinkType, type BggThingMarketplaceListing, type BggThingName, type BggThingParams, type BggThingResponse, type BggThingVideo, type BggThreadParams, type BggThreadResponse, type BggUserParams, type BggUserResponse, type BggVideogameItem, type BggVideogameLinkType, type ClientOptions, type GeeklistParams, type GeeklistResponse, type OfValue, type OneOrNothing, type ResourceName, type SearchType, type SingleOrMany, type ThingType, type XmlParser, type XmlString, bggXmlApiClient, getBggCollection, getBggFamily, getBggForum, getBggForumlist, getBggGeeklist, getBggGuild, getBggHot, getBggPlays, getBggSearch, getBggThing, getBggThread, getBggUser };