initial commit for v1

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.js]
+indent_style = space
+indent_size = 2
+
+[{package.json,*.yml,*.cjson}]
+indent_style = space
+indent_size = 2

.eslintignore

@@ -0,0 +1,4 @@
+dist
+node_modules
+*.json
+*.md

.eslintrc

@@ -0,0 +1,21 @@
+{
+  "extends": [
+    "eslint-config-unjs"
+  ],
+  "rules": {
+    "no-undef": 0,
+    "unicorn/consistent-destructuring": 0,
+    "unicorn/no-await-expression-member": 0,
+    "unicorn/numeric-separators-style": 0,
+    "no-irregular-whitespace": 0,
+    "quotes": ["error", "single"],
+    "indent": ["error", 2],
+    "no-multiple-empty-lines": ["error", { "max": 1, "maxEOF": 1 }],
+    "unused-imports/no-unused-imports": "error",
+    "no-trailing-spaces": ["error"],
+    "curly": ["error", "multi"]
+  },
+  "plugins": [
+    "unused-imports"
+  ]
+}

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: corepack enable
+      - name: Install bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      - name: Install dependencies
+        run: bun install
+      - run: bun lint
+      - run: bun typecheck
+      - run: bun test
+

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+logs

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Steven Schoovaerts <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,7 @@
+# BGG API Parser
+
+## Description
+
+The goal of this package is to provide a simple way to parse the XML data provided by the [BoardGameGeek API](https://boardgamegeek.com/wiki/page/BGG_XML_API). It takes an opinionated approach to the parsed data, renaming properies and culling properties that are not useful for the majority of use cases. The package was primarily written to support my own private board game collection application, but I hope it can be useful to others as well.
+
+Feel free to open an issue or pull request if you have any suggestions or find any bugs.

build.config.ts

@@ -0,0 +1,17 @@
+import path, { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+  declaration: true,
+  rollup: {
+    emitCJS: true
+  },
+  entries: [
+    'src/index',
+  ],
+  alias: {
+    '@': resolve(path.dirname(fileURLToPath(import.meta.url)), 'src'),
+    // '@': resolve(__dirname, 'src'),
+  },
+});

node.d.ts

@@ -0,0 +1 @@
+export * from './dist/node'

package.json

@@ -0,0 +1,73 @@
+{
+  "name": "bgg-api-wrapper",
+  "version": "1.0.0",
+  "description": "Parses XML responses from the Boardgamegeek API in an opinionated way.",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "browser": "./dist/index.mjs",
+      "bun": "./dist/index.mjs",
+      "deno": "./dist/index.mjs",
+      "edge-light": "./dist/index.mjs",
+      "edge-routine": "./dist/index.mjs",
+      "lagon": "./dist/index.mjs",
+      "netlify": "./dist/index.mjs",
+      "react-native": "./dist/index.mjs",
+      "wintercg": "./dist/index.mjs",
+      "worker": "./dist/index.mjs",
+      "workerd": "./dist/index.mjs",
+      "node": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.cjs"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.cjs"
+      }
+    },
+    "./node": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "node.d.ts"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "lint": "eslint --ext .ts .",
+    "lint:fix": "eslint --fix --ext .ts .",
+    "prepack": "bun run build",
+    "play": "bun run playground/index.ts",
+    "release": "bun test && changelogen --release && npm publish && git push --follow-tags",
+    "test": "bun run lint && bun test --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "fast-xml-parser": "^4.2.4",
+    "ofetch": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.7",
+    "bun-types": "^1.0.7",
+    "changelogen": "^0.5.5",
+    "eslint": "^8.52.0",
+    "eslint-config-unjs": "^0.2.1",
+    "eslint-plugin-unused-imports": "^3.0.0",
+    "typescript": "^5.2.2",
+    "unbuild": "^2.0.0"
+  },
+  "packageManager": "[email protected]"
+}

playground/index.ts

@@ -0,0 +1,9 @@
+import { findGameByIds } from 'src/api/games/find-game-by-id';
+
+findGameByIds([18, 19], {
+  comments: true,
+  historical: true,
+  stats: true,
+})
+// findGame('stroganov')
+// findCollection('vanskillz')

src/api/games/collection.ts

@@ -0,0 +1,55 @@
+import { writeFileSync } from 'node:fs'
+import { ofetch } from 'ofetch'
+import { xmlParser , mergeAttributes } from '../../utils/parser'
+import { Collection } from 'src/types/collection'
+
+interface MergedResult {
+  items: {
+    item: MergedResultItem[]
+    totalitems: number
+  }
+}
+
+interface MergedResultItem {
+  id: number
+  titles: Array<{
+    name: string
+  }>,
+  yearPublished: number
+  image: string
+  thumbnail: string
+}
+
+function parseItem(item: MergedResultItem) {
+  return {
+    id: item.id,
+    title: item.titles[0].name,
+    yearPublished: item.yearPublished,
+    image: item.image,
+    thumbnail: item.thumbnail,
+  }
+}
+
+export function parseCollection(xmlString: string): Collection {
+  const resultParsed = xmlParser.parse(xmlString)
+  const mergedItems: MergedResult = mergeAttributes(resultParsed)
+  const mergedGames = mergedItems.items.item
+  const games = mergedGames.map((item: MergedResultItem) => parseItem(item))
+  const collection: Collection = {
+    numberOfGames: mergedItems.items.totalitems,
+    games,
+  }
+  // writeFileSync('logs/collection.json', JSON.stringify(collection, undefined, 2));
+  return collection
+}
+
+export async function findCollection(userName: string) {
+  const searchParams = new URLSearchParams({
+    own: '1',
+  })
+  const response = await ofetch<string>(
+    `https://www.boardgamegeek.com/xmlapi/collection/${userName}?${searchParams}`
+  )
+  writeFileSync('logs/collection.xml', response)
+  parseCollection(response)
+}

src/api/games/find-game-by-id.ts

@@ -0,0 +1,106 @@
+import { writeFileSync } from 'node:fs'
+import { ofetch } from 'ofetch'
+import { mergeAttributes, parsePoll, xmlParser } from '../../utils/parser.js'
+import { renameProperties } from '../../utils/names.js'
+import type { Game } from 'src/types/games.js'
+
+export interface findGameByIdOptions {
+  comments?: boolean
+  historical?: boolean
+  stats?: boolean
+}
+
+/**
+ * Takes in an XML string from BGG and returns a Game object
+ * @param xmlResponse The XML response from BGG
+ * @returns A Game object representing the parsed game.
+ */
+export function parseFindGameById(xmlString: string) {
+  const resultParsed = xmlParser.parse(xmlString)
+  // writeFileSync('logs/find-game-by-id-parsed-xml.json', JSON.stringify(resultParsed, undefined, 2));
+  const resultMerged = mergeAttributes(resultParsed)
+  // writeFileSync('logs/find-game-by-id-merged.json', JSON.stringify(resultMerged, undefined, 2));
+  const game = parseFindGameByIdGame(resultMerged.boardgames.boardgame[0])
+  // writeFileSync('logs/find-game-by-id.json', JSON.stringify(result, undefined, 2));
+  return game
+}
+
+/**
+ * Takes in an XML string from BGG and returns an array of Game objects
+ * @param xmlResponse The XML response from BGG
+ * @returns An array of game objects representing the parsed games.
+ */
+export function parseFindGameByIds(xmlString: string) {
+  const resultParsed = xmlParser.parse(xmlString)
+  // writeFileSync('logs/find-game-by-ids-parsed-xml.json', JSON.stringify(resultParsed, undefined, 2));
+  const resultMerged = mergeAttributes(resultParsed)
+  writeFileSync('logs/find-game-by-ids-merged.json', JSON.stringify(resultMerged, undefined, 2));
+  const games = resultMerged.boardgames.boardgame.map(
+    (game: Record<string, any>) => parseFindGameByIdGame(game)
+  )
+  writeFileSync('logs/find-game-by-ids.json', JSON.stringify(games, undefined, 2));
+  return games
+}
+
+/**
+ * Parses the parsed XML object of a game retrieved by its ID and returns a Game object.
+ * @param rawGame The parsed XML object of the game to parse.
+ * @returns A Game object representing the parsed game.
+ */
+export function parseFindGameByIdGame(merged: Record<string, any>): Game {
+  const parsedPoll = parsePoll(merged.poll)
+  // writeFileSync('logs/poll.json', JSON.stringify(parsedPoll, undefined, 2));
+  delete merged.poll
+  merged = {
+    ...merged,
+    ...parsedPoll,
+  }
+  const resultRenamedProperties = renameProperties(merged)
+  return resultRenamedProperties as Game
+}
+
+/**
+ * Finds a board game by its ID on BGG.
+ * @param id The id of the board game to find.
+ * @param options Additional options for the search
+ * @param options.comments Whether to include comments in the result.
+ * @param options.historical Whether to include historical data in the result.
+ * @param options.stats Whether to include stats in the result.
+ * @returns A Promise that resolves to the found board game.
+ */
+export async function findGameById(id: number, options: findGameByIdOptions = {}) {
+  const searchParams = new URLSearchParams({
+    ...(options.comments && { comments: '1' }),
+    ...(options.historical && { historical: '1' }),
+    ...(options.stats && { stats: '1' }),
+  })
+  const response = await ofetch<string>(
+    `https://www.boardgamegeek.com/xmlapi/boardgame/${id}?${searchParams}`
+  )
+  // writeFileSync('logs/find-game-by-id.xml', response);
+  const result = parseFindGameById(response)
+  return result
+}
+
+/**
+ * Find multiple board games by their ID on BGG.
+ * @param ids The ids of the board games to find.
+ * @param options Additional options for the search
+ * @param options.comments Whether to include comments in the result.
+ * @param options.historical Whether to include historical data in the result.
+ * @param options.stats Whether to include stats in the result.
+ * @returns A Promise that resolves to the found board game.
+ */
+export async function findGameByIds(ids: number[], options: findGameByIdOptions = {}) {
+  const searchParams = new URLSearchParams({
+    ...(options.comments && { comments: '1' }),
+    ...(options.historical && { historical: '1' }),
+    ...(options.stats && { stats: '1' }),
+  })
+  const response = await ofetch<string>(
+    `https://www.boardgamegeek.com/xmlapi/boardgame/${ids.join(',')}?${searchParams}`
+  )
+  writeFileSync('logs/find-game-by-ids.xml', response);
+  const result = parseFindGameByIds(response)
+  return result
+}