halo-infinite-api 12.0.1 → 12.0.2

package/.editorconfig

@@ -1,13 +1,13 @@
-# Editor configuration, see http://editorconfig.org
-root = true
-
-[*]
-charset = utf-8
-indent_style = space
-indent_size = 2
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-max_line_length = off
-trim_trailing_whitespace = false
+# Editor configuration, see http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  build-test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test --ignore-scripts --if-present -- --ci --reporters=default --errorOnDeprecated
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify no uncommitted changes after build
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo '::error::Build generated uncommitted changes. Please commit build artifacts or adjust build.'
+            git diff --name-only
+            exit 1
+          fi
+
+    # Optionally only run build on PRs from forks if necessary secrets are not required
+    # strategy: {}

package/.github/workflows/npm-publish.yml

@@ -1,22 +1,22 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Node.js Package
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish-npm:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write # for creating a release
+  packages: write
+
+jobs:
+  publish:
+    name: Build, Test, Publish & Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test --ignore-scripts --if-present
+
+      - name: Build
+        run: npm run build
+
+      - name: Derive version from tag
+        id: version
+        run: |
+          TAG_REF="${GITHUB_REF##*/}"
+          echo "tag=$TAG_REF" >> $GITHUB_OUTPUT
+          # Optional: verify package.json version matches tag
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$PKG_VERSION" != "$TAG_REF" ]; then
+            echo "::warning::Tag ($TAG_REF) does not match package.json version ($PKG_VERSION). Continuing, but consider publishing a matching version.";
+          fi
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm publish --access public
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 --match "[0-9]*.[0-9]*.[0-9]*" $(git rev-list --tags --max-count=2) | tail -n1 || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            COMMITS=$(git log --pretty=format:'- %s')
+          else
+            COMMITS=$(git log "$PREV_TAG..HEAD" --pretty=format:'- %s')
+          fi
+          echo "commits<<'EOF'" >> $GITHUB_OUTPUT
+          echo "$COMMITS" >> $GITHUB_OUTPUT
+          echo 'EOF' >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          release_name: v${{ steps.version.outputs.tag }}
+          body: ${{ steps.notes.outputs.commits }}
+          draft: false
+          prerelease: false

package/.vscode/settings.json

@@ -1,3 +1,6 @@
-{
-  "javascript.preferences.importModuleSpecifier": "relative"
-}
+{
+  "javascript.preferences.importModuleSpecifier": "relative",
+  "explorer.fileNesting.patterns": {
+    "*.ts": "${capture}.test.ts"
+  }
+}

package/README.md

@@ -1,67 +1,93 @@
-# Halo Infinite API
-
-This is a simple typescript wrapper around 343's official Halo Infinite API (the same API that powers both the game and [halowaypoint.com](https://www.halowaypoint.com/)). I based it off the work of the now mysteriously deleted C# Grunt API (a defunct fork of which remains [here](https://github.com/seth-skocelas/grunt/)).
-
-The package is currently limited to the endpoints I've needed to use in other projects, however I do take requests (create an [issue](/issues)) and I welcome [PRs to extend the functionality](/pulls).
-
-### Currently Supported Endpoints
-
-- GET https://profile.svc.halowaypoint.com/users/{gamerTag}
-- GET https://profile.svc.halowaypoint.com/users?xuids={xuids}
-- GET https://skill.svc.halowaypoint.com/hi/playlist/{playlistId}/csrs?players={playerIds}
-- GET https://skill.svc.halowaypoint.com/hi/matches/{matchId}/skill
-- GET https://gamecms-hacs.svc.halowaypoint.com/hi/multiplayer/file/playlists/assets/{playlistId}.json
-- GET https://gamecms-hacs.svc.halowaypoint.com/hi/Progression/file/{filename}.json
-- GET https://halostats.svc.halowaypoint.com/hi/playlist/{playlistId}/csrs?players={playerIds}
-- GET https://halostats.svc.halowaypoint.com/hi/players/xuid({playerId})/matches
-- GET https://halostats.svc.halowaypoint.com/hi/players/{gamerTagOrWrappedXuid}/Matchmade/servicerecord
-- GET https://halostats.svc.halowaypoint.com/hi/matches/{matchId}/stats
-- GET https://discovery-infiniteugc.svc.halowaypoint.com/hi/{assetType}/{assetId}
-- GET https://discovery-infiniteugc.svc.halowaypoint.com/hi/{assetType}/{assetId}/versions/{versionId}
-
-### Getting Started
-
-The core requirement to use the endpoints in the library is to have a Spartan token, that is provided by the Halo Infinite service.
-
-> **⚠️ WARNING**
->
-> The Spartan token is associated with _your identity_ and _your account_. **Do not share it** with anyone, under any circumstances. The API wrapper does not explicitly store it anywhere (though you can configure it to store it somewhere of your choosing). It's your responsibility to make sure that it's secure and not available to anyone else.
-
-This library does not provide a way to perform the first step of generating a spartan token, which is to get an Oauth2 access token from Microsoft. Microsoft provides a great set of npm packages for this purpose, [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node), [@azure/msal-browser](https://www.npmjs.com/package/@azure/msal-browser), [@azure/msal-react](https://www.npmjs.com/package/@azure/msal-react), etc. depending on the flavor of your application.
-
-Make sure that you [register an Azure Active Directory application](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app), as that is how you will make use of the @azure/msal packages.
-
-Below is a simple example of how this library might be used in a console application to get a user's profile:
-
-```typescript
-import open from "open"; // An npm package that opens a browser window
-import * as msal from "@azure/msal-node";
-import { HaloInfiniteClient, AutoXstsSpartanTokenProvider } from "halo-infinite-api";
-
-const oauthApplication = new msal.PublicClientApplication({
-  auth: {
-    clientId: "00000000-0000-0000-0000-000000000000",
-    authority: "https://login.live.com", // Override the default authority with the xbox one
-    knownAuthorities: ["login.live.com"],
-    protocolMode: "OIDC", // Shit, I actually have no idea what this does, but Microsoft says I need it
-  },
-});
-
-const client = new HaloInfiniteClient(
-  // Another choice for token providers is the StaticXstsTicketTokenSpartanTokenProvider,
-  // which uses a preset spartan token
-  new AutoTokenProvider(async () => {
-    const token = await oauthApplication.acquireTokenInteractive({
-      // offline_access gives us a refresh token which we can use to continually
-      // get new credentials from Microsoft as the old ones expire.
-      scopes: ["Xboxlive.signin", "Xboxlive.offline_access"],
-      openBrowser: async (url) => {
-        await open(url);
-      },
-    });
-    return token.accessToken;
-  })
-);
-
-const user = await client.getUser("GravlLift");
-```
+# Halo Infinite API
+
+This is a simple typescript wrapper around 343's official Halo Infinite API (the same API that powers both the game and [halowaypoint.com](https://www.halowaypoint.com/)). I based it off the work of the now mysteriously deleted C# Grunt API (a defunct fork of which remains [here](https://github.com/seth-skocelas/grunt/)).
+
+The package is currently limited to the endpoints I've needed to use in other projects, however I do take requests (create an [issue](/issues)) and I welcome [PRs to extend the functionality](/pulls).
+
+### Currently Supported Endpoints
+
+- GET https://profile.svc.halowaypoint.com/users/{gamerTag}
+- GET https://profile.svc.halowaypoint.com/users?xuids={xuids}
+- GET https://skill.svc.halowaypoint.com/hi/playlist/{playlistId}/csrs?players={playerIds}
+- GET https://skill.svc.halowaypoint.com/hi/matches/{matchId}/skill
+- GET https://gamecms-hacs.svc.halowaypoint.com/hi/multiplayer/file/playlists/assets/{playlistId}.json
+- GET https://gamecms-hacs.svc.halowaypoint.com/hi/Progression/file/{filename}.json
+- GET https://halostats.svc.halowaypoint.com/hi/playlist/{playlistId}/csrs?players={playerIds}
+- GET https://halostats.svc.halowaypoint.com/hi/players/xuid({playerId})/matches
+- GET https://halostats.svc.halowaypoint.com/hi/players/{gamerTagOrWrappedXuid}/Matchmade/servicerecord
+- GET https://halostats.svc.halowaypoint.com/hi/matches/{matchId}/stats
+- GET https://discovery-infiniteugc.svc.halowaypoint.com/hi/{assetType}/{assetId}
+- GET https://discovery-infiniteugc.svc.halowaypoint.com/hi/{assetType}/{assetId}/versions/{versionId}
+
+### Getting Started
+
+The core requirement to use the endpoints in the library is to have a Spartan token, that is provided by the Halo Infinite service.
+
+> **⚠️ WARNING**
+>
+> The Spartan token is associated with _your identity_ and _your account_. **Do not share it** with anyone, under any circumstances. The API wrapper does not explicitly store it anywhere (though you can configure it to store it somewhere of your choosing). It's your responsibility to make sure that it's secure and not available to anyone else.
+
+This library does not provide a way to perform the first step of generating a spartan token, which is to get an Oauth2 access token from Microsoft. Microsoft provides a great set of npm packages for this purpose, [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node), [@azure/msal-browser](https://www.npmjs.com/package/@azure/msal-browser), [@azure/msal-react](https://www.npmjs.com/package/@azure/msal-react), etc. depending on the flavor of your application.
+
+Make sure that you [register an Azure Active Directory application](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app), as that is how you will make use of the @azure/msal packages.
+
+Below is a simple example of how this library might be used in a console application to get a user's profile:
+
+```typescript
+import open from "open"; // An npm package that opens a browser window
+import * as msal from "@azure/msal-node";
+import { HaloInfiniteClient, AutoXstsSpartanTokenProvider } from "halo-infinite-api";
+
+const oauthApplication = new msal.PublicClientApplication({
+  auth: {
+    clientId: "00000000-0000-0000-0000-000000000000",
+    authority: "https://login.live.com", // Override the default authority with the xbox one
+    knownAuthorities: ["login.live.com"],
+    protocolMode: "OIDC", // Shit, I actually have no idea what this does, but Microsoft says I need it
+  },
+});
+
+const client = new HaloInfiniteClient(
+  // Another choice for token providers is the StaticXstsTicketTokenSpartanTokenProvider,
+  // which uses a preset spartan token
+  new AutoTokenProvider(async () => {
+    const token = await oauthApplication.acquireTokenInteractive({
+      // offline_access gives us a refresh token which we can use to continually
+      // get new credentials from Microsoft as the old ones expire.
+      scopes: ["Xboxlive.signin", "Xboxlive.offline_access"],
+      openBrowser: async (url) => {
+        await open(url);
+      },
+    });
+    return token.accessToken;
+  })
+);
+
+const user = await client.getUser("GravlLift");
+```
+
+### Releasing / Publishing
+
+A GitHub Action automatically publishes the package to npm and creates a GitHub Release whenever you push a semantic version tag (format: `<major>.<minor>.<patch>`, e.g. `12.0.2`).
+
+Steps to cut a release:
+
+1. Update the version in `package.json` according to semver rules.
+2. Commit the change (e.g. `git commit -am "chore: release 12.0.2"`).
+3. Create and push the tag:
+   ```bash
+   git tag 12.0.2
+   git push origin 12.0.2
+   ```
+4. The workflow will:
+   - Install dependencies, run tests, and build
+   - Publish to npm (using the `NPM_TOKEN` secret)
+   - Create a GitHub Release with commit messages since the previous tag
+
+Required repository secrets:
+
+- `NPM_TOKEN` – An npm access token with `publish` permission.
+
+If the tag version doesn't match `package.json` the workflow will warn, but will still publish using the `package.json` version.
+
+Ensure the package has the correct access level (public) on npm before the first automated publish.