@retroachievements/api 1.5.3 → 2.1.0

package/dist/user/models/game-info-and-user-progress.model.d.ts

@@ -1,4 +1,5 @@
 import type { GameExtended, GameExtendedAchievementEntity } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 export type GameExtendedAchievementEntityWithUserProgress = GameExtendedAchievementEntity & {
     dateEarned: string;
     dateEarnedHardcore: string;
@@ -9,4 +10,6 @@ export interface GameInfoAndUserProgress extends GameExtended {
     numAwardedToUserHardcore: number;
     userCompletion: string;
     userCompletionHardcore: string;
+    highestAwardKind?: AwardKind | null;
+    highestAwardDate?: string;
 }

package/dist/user/models/get-game-info-and-user-progress-response.model.d.ts

@@ -1,4 +1,5 @@
 import type { GameExtendedRawAchievementEntity, GetGameExtendedResponse } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 type GetGameExtendedResponseWithoutClaims = Omit<GetGameExtendedResponse, "Claims">;
 type GameExtendedRawAchievementEntityWithUserProgress = GameExtendedRawAchievementEntity & {
     DateEarned: string;
@@ -10,5 +11,7 @@ export interface GetGameInfoAndUserProgressResponse extends GetGameExtendedRespo
     NumAwardedToUserHardcore: number;
     UserCompletion: string;
     UserCompletionHardcore: string;
+    HighestAwardKind?: AwardKind | null;
+    HighestAwardDate?: string;
 }
 export {};

package/dist/user/models/get-user-completion-progress-response.model.d.ts

@@ -1,3 +1,4 @@
+import type { AwardKind } from "../../utils/public";
 interface RawUserCompletionProgressEntity {
     GameID: number;
     Title: string;
@@ -8,7 +9,7 @@ interface RawUserCompletionProgressEntity {
     NumAwarded: number;
     NumAwardedHardcore: number;
     MostRecentAwardedDate?: string;
-    HighestAwardKind?: "mastered" | "completed" | "beaten-hardcore" | "beaten-softcore" | null;
+    HighestAwardKind?: AwardKind | null;
     HighestAwardDate?: string | null;
 }
 export interface GetUserCompletionProgressResponse {

package/dist/user/models/user-completion-progress-entity.model.d.ts

@@ -1,3 +1,4 @@
+import type { AwardKind } from "../../utils/public";
 export interface UserCompletionProgressEntity {
     gameId: number;
     title: string;
@@ -8,6 +9,6 @@ export interface UserCompletionProgressEntity {
     numAwarded: number;
     numAwardedHardcore: number;
     mostRecentAwardedDate?: string;
-    highestAwardKind?: "mastered" | "completed" | "beaten-hardcore" | "beaten-softcore" | null;
+    highestAwardKind?: AwardKind | null;
     highestAwardDate?: string;
 }

package/dist/utils/public/buildAuthorization.d.ts

@@ -14,7 +14,7 @@ import type { AuthObject } from "./models";
  * @example
  * ```
  * const authorization = buildAuthorization({
- *   userName: "Scott",
+ *   username: "Scott",
  *   webApiKey: "LtjCwW16nJI7cqOyPIQtXk8v1cfF0tmO"
  * });
  * ```

package/dist/utils/public/models/auth-object.model.d.ts

@@ -1,6 +1,6 @@
 /**
  * Each RetroAchievements API call is uniquely authenticated
- * using a userName + API key combination. Your account's personal
+ * using a username + API key combination. Your account's personal
  * Web API Key can be found on the Settings page.
  */
 export interface AuthObject {
@@ -9,7 +9,7 @@ export interface AuthObject {
      * For example, https://retroachievements.org/user/Scott would have a value
      * of "Scott".
      */
-    userName: string;
+    username: string;
     /**
      * This can be found in the "Keys" section of your Settings page on the
      * RetroAchievements.org website. This is a 32-digit alphanumeric key

package/dist/utils/public/models/award-kind.model.d.ts

@@ -0,0 +1 @@
+export type AwardKind = "beaten-softcore" | "beaten-hardcore" | "completed" | "mastered";

package/dist/utils/public/models/index.d.ts

@@ -1 +1,2 @@
 export * from "./auth-object.model";
+export * from "./award-kind.model";

package/package.json

@@ -10,7 +10,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "1.5.3",
+  "version": "2.1.0",
   "typings": "dist/index.d.ts",
   "exports": {
     ".": {
@@ -32,7 +32,7 @@
     "dev": "esrun --watch src/__playground.ts",
     "prebuild": "node src/set-version.js",
     "build": "microbundle",
-    "prepare": "microbundle",
+    "prepare": "microbundle && husky install",
     "format": "prettier --write . '**/*.{json,md,js,ts,tsx}'",
     "format:write": "prettier --write . '**/*.{json,md,js,ts,tsx}'",
     "format:check": "prettier --check . '**/*.{json,md,js,ts,tsx}'",
@@ -41,10 +41,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "verify": "yarn format:check && yarn lint && yarn test:coverage && yarn build",
+    "verify": "pnpm format:check && pnpm lint && pnpm test:coverage && pnpm build",
     "start": "microbundle watch"
   },
-  "peerDependencies": {},
   "devDependencies": {
     "@commitlint/cli": "^17.4.2",
     "@commitlint/config-conventional": "^17.4.2",
@@ -62,7 +61,7 @@
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "eslint-plugin-sonarjs": "^0.23.0",
     "eslint-plugin-unicorn": "^49.0.0",
-    "husky": "4.3.8",
+    "husky": "9.0.11",
     "microbundle": "^0.15.1",
     "msw": "^2.0.3",
     "prettier": "2.8.3",
@@ -74,12 +73,6 @@
     "vite": "^4.5.0",
     "vitest": "^0.34.6"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "pretty-quick --staged && yarn lint",
-      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-    }
-  },
   "config": {
     "commitizen": {
       "path": "./node_modules/cz-conventional-changelog"
@@ -102,5 +95,6 @@
     "url": "https://github.com/RetroAchievements/api-js/issues"
   },
   "homepage": "https://github.com/RetroAchievements/api-js#readme",
-  "author": "RAWeb Team"
+  "author": "RAWeb Team",
+  "packageManager": "pnpm@9.1.1+sha256.9551e803dcb7a1839fdf5416153a844060c7bce013218ce823410532504ac10b"
 }

package/src/__playground.ts

@@ -17,7 +17,7 @@
 import { buildAuthorization, getAchievementCount } from "./index";
 
 // MODIFY THESE VALUES.
-const userName = "myUserName";
+const username = "myUsername";
 const webApiKey = "myWebApiKey";
 
 const main = async () => {
@@ -25,13 +25,13 @@ const main = async () => {
 
   // -- Start testing stuff here --
 
-  if (userName === "myUserName" || webApiKey === "myWebApiKey") {
+  if (username === "myUsername" || webApiKey === "myWebApiKey") {
     console.error(
-      "⛔️  ERROR: In __playground.ts, modify the userName and webApiKey variables to match your RA credentials.\n"
+      "⛔️  ERROR: In __playground.ts, modify the username and webApiKey variables to match your RA credentials.\n"
     );
   }
 
-  const authorization = buildAuthorization({ userName, webApiKey });
+  const authorization = buildAuthorization({ username, webApiKey });
 
   const achievementCount = await getAchievementCount(authorization, {
     gameId: 14_402,

package/src/achievement/getAchievementUnlocks.test.ts

@@ -22,7 +22,7 @@ describe("Function: getAchievementUnlocks", () => {
   it("retrieves metadata about unlocks for a target achievement", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/achievement/getAchievementUnlocks.ts

@@ -15,7 +15,7 @@ import type {
  * A call to this function will retrieve a list of users who
  * have earned a given achievement, targeted by the achievement's ID.
  *
- * @param authorization An object containing your userName and webApiKey.
+ * @param authorization An object containing your username and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
  * @param payload.achievementId The target achievement we want to

package/src/console/getConsoleIds.test.ts

@@ -6,7 +6,7 @@ import { setupServer } from "msw/node";
 import { apiBaseUrl } from "../utils/internal";
 import { buildAuthorization } from "../utils/public";
 import { getConsoleIds } from "./getConsoleIds";
-import type { ConsoleId, GetConsoleIdsResponse } from "./models";
+import type { FetchedSystem, GetConsoleIdsResponse } from "./models";
 
 const server = setupServer();
 
@@ -24,7 +24,7 @@ describe("Function: getConsoleIds", () => {
   it("retrieves a list of console IDs and their names and cleans properties", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -34,18 +34,24 @@ describe("Function: getConsoleIds", () => {
         Name: "Mega Drive",
         IconURL:
           "https://static.retroachievements.org/assets/images/system/md.png",
+        Active: true,
+        IsGameSystem: true,
       },
       {
         ID: "2",
         Name: "Nintendo 64",
         IconURL:
           "https://static.retroachievements.org/assets/images/system/n64.png",
+        Active: true,
+        IsGameSystem: true,
       },
       {
         ID: "3",
         Name: "SNES",
         IconURL:
           "https://static.retroachievements.org/assets/images/system/snes.png",
+        Active: false,
+        IsGameSystem: false,
       },
     ];
 
@@ -59,24 +65,30 @@ describe("Function: getConsoleIds", () => {
     const response = await getConsoleIds(authorization);
 
     // ASSERT
-    const expectedResponse: ConsoleId[] = [
+    const expectedResponse: FetchedSystem[] = [
       {
         id: 1,
         name: "Mega Drive",
         iconUrl:
           "https://static.retroachievements.org/assets/images/system/md.png",
+        active: true,
+        isGameSystem: true,
       },
       {
         id: 2,
         name: "Nintendo 64",
         iconUrl:
           "https://static.retroachievements.org/assets/images/system/n64.png",
+        active: true,
+        isGameSystem: true,
       },
       {
         id: 3,
         name: "SNES",
         iconUrl:
           "https://static.retroachievements.org/assets/images/system/snes.png",
+        active: false,
+        isGameSystem: false,
       },
     ];
 

package/src/console/getConsoleIds.ts

@@ -5,16 +5,22 @@ import {
   serializeProperties,
 } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
-import type { ConsoleId, GetConsoleIdsResponse } from "./models";
+import type { FetchedSystem, GetConsoleIdsResponse } from "./models";
 
 /**
  * A call to this function will retrieve the complete list
  * of console ID and name pairs on the RetroAchievements.org
  * platform.
  *
- * @param authorization An object containing your userName and webApiKey.
+ * @param authorization An object containing your username and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
+ * @param payload.shouldOnlyRetrieveActiveSystems If true, only systems that
+ * officially support achievements will be returned.
+ *
+ * @param payload.shouldOnlyRetrieveGameSystems If true, events and hubs will
+ * not be returned.
+ *
  * @example
  * ```
  * const consoleIds = await getConsoleIds(authorization);
@@ -26,17 +32,33 @@ import type { ConsoleId, GetConsoleIdsResponse } from "./models";
  * {
  *   id: "1",
  *   name: "Mega Drive",
- *   iconUrl: "https://static.retroachievements.org/assets/images/system/md.png"
+ *   iconUrl: "https://static.retroachievements.org/assets/images/system/md.png",
+ *   active: true,
+ *   isGameSystem: true
  * }
  * ```
  */
 export const getConsoleIds = async (
-  authorization: AuthObject
-): Promise<ConsoleId[]> => {
+  authorization: AuthObject,
+  payload?: {
+    shouldOnlyRetrieveActiveSystems: boolean;
+    shouldOnlyRetrieveGameSystems: boolean;
+  }
+): Promise<FetchedSystem[]> => {
+  let callPayload: Record<string, any> | undefined;
+
+  if (payload?.shouldOnlyRetrieveActiveSystems) {
+    callPayload = { ...callPayload, a: 1 };
+  }
+  if (payload?.shouldOnlyRetrieveGameSystems) {
+    callPayload = { ...callPayload, g: 1 };
+  }
+
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetConsoleIDs.php",
-    authorization
+    authorization,
+    callPayload
   );
 
   const rawResponse = await call<GetConsoleIdsResponse>({ url });

package/src/console/getGameList.test.ts

@@ -24,7 +24,7 @@ describe("Function: getGameList", () => {
   it("retrieves a list of games and cleans their properties", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/console/getGameList.ts

@@ -12,7 +12,7 @@ import type { GameList, GetGameListResponse } from "./models";
  * of games for a specified console on the RetroAchievements.org
  * platform.
  *
- * @param authorization An object containing your userName and webApiKey.
+ * @param authorization An object containing your username and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
  * @param payload.consoleId The unique console ID to retrieve a list of

package/src/console/models/fetched-system.model.ts

@@ -0,0 +1,7 @@
+export interface FetchedSystem {
+  id: number;
+  name: string;
+  iconUrl: string;
+  active: boolean;
+  isGameSystem: boolean;
+}

package/src/console/models/get-console-ids-response.model.ts

@@ -2,4 +2,6 @@ export type GetConsoleIdsResponse = readonly {
   ID: string;
   Name: string;
   IconURL: string;
+  Active: boolean;
+  IsGameSystem: boolean;
 }[];

package/src/console/models/index.ts

@@ -1,4 +1,4 @@
-export * from "./console-id.model";
+export * from "./fetched-system.model";
 export * from "./game-list.model";
 export * from "./get-console-ids-response.model";
 export * from "./get-game-list-response.model";

package/src/feed/getAchievementOfTheWeek.test.ts

@@ -27,7 +27,7 @@ describe("Function: getAchievementOfTheWeek", () => {
   it("retrieves metadata about the current achievement of the week and cleans properties", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -105,7 +105,7 @@ describe("Function: getAchievementOfTheWeek", () => {
   it("properly sets the hardcore boolean value when cleaning properties", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/feed/getAchievementOfTheWeek.ts

@@ -14,7 +14,7 @@ import type {
  * A call to this function will retrieve comprehensive
  * metadata about the current Achievement of the Week.
  *
- * @param authorization An object containing your userName and webApiKey.
+ * @param authorization An object containing your username and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
  * @example

package/src/feed/getActiveClaims.test.ts

@@ -24,7 +24,7 @@ describe("Function: getActiveClaims", () => {
   it("retrieves metadata about current active claims", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/feed/getActiveClaims.ts

@@ -11,7 +11,7 @@ import type { GetSetClaimsResponse, SetClaim } from "./models";
  * A call to this function returns information about all
  * (1000 max) active set claims.
  *
- * @param authorization An object containing your userName and webApiKey.
+ * @param authorization An object containing your username and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
  * @example

package/src/feed/getClaims.test.ts

@@ -24,7 +24,7 @@ describe("Function: getClaims", () => {
   it("retrieves metadata about a requested kind of claims", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/feed/getRecentGameAwards.test.ts

@@ -0,0 +1,73 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getRecentGameAwards } from "./getRecentGameAwards";
+import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
+
+const server = setupServer();
+
+describe("Function: getRecentGameAwards", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getRecentGameAwards).toBeDefined();
+  });
+
+  it("retrieves metadata about all recently-earned game awards on the site", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetRecentGameAwardsResponse = {
+      Count: 1,
+      Total: 1,
+      Results: [
+        {
+          User: "renanbrj",
+          AwardKind: "mastered",
+          AwardDate: "2022-01-01T23:48:04+00:00",
+          GameID: 14_284,
+          GameTitle: "Batman Returns",
+          ConsoleID: 15,
+          ConsoleName: "Game Gear",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetRecentGameAwards.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getRecentGameAwards(authorization);
+
+    const expectedResponse: RecentGameAwards = {
+      count: 1,
+      total: 1,
+      results: [
+        {
+          user: "renanbrj",
+          awardKind: "mastered",
+          awardDate: "2022-01-01T23:48:04+00:00",
+          gameId: 14_284,
+          gameTitle: "Batman Returns",
+          consoleId: 15,
+          consoleName: "Game Gear",
+        },
+      ],
+    };
+
+    // ASSERT
+    expect(response).toEqual(expectedResponse);
+  });
+});

package/src/feed/getRecentGameAwards.ts

@@ -0,0 +1,85 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties,
+} from "../utils/internal";
+import type { AuthObject, AwardKind } from "../utils/public";
+import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
+
+/**
+ * A call to this function will retrieve all recently granted game
+ * awards across the site's userbase.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.startDate The date to fetch awards from.
+ *
+ * @param payload.offset Optional. Defaults to 0.
+ *
+ * @param payload.count Optional. Defaults to 25.
+ *
+ * @param payload.desiredAwardKinds Optional. Defaults to all. Accepts "beaten-softcore", "beaten-hardcore", "completed", and/or "mastered".
+ *
+ * @example
+ * ```
+ * const recentGameAwards = await getRecentGameAwards(
+ *   authorization,
+ * );
+ * ```
+ *
+ * @returns An object containing metadata about all recently granted game
+ * awards across the site's userbase
+ * ```
+ * {
+ *   count: 1,
+ *   total: 1,
+ *   results: [
+ *     {
+ *       user: "renanbrj",
+ *       awardKind: "mastered",
+ *       awardDate: "2022-01-01T23:48:04+00:00",
+ *       gameId: 14_284,
+ *       gameTitle: "Batman Returns",
+ *       consoleId: 15,
+ *       consoleName: "Game Gear",
+ *     },
+ *   ],
+ * }
+ * ```
+ */
+export const getRecentGameAwards = async (
+  authorization: AuthObject,
+  payload?: Partial<{
+    startDate: string;
+    offset: number;
+    count: number;
+    desiredAwardKinds: AwardKind[];
+  }>
+): Promise<RecentGameAwards> => {
+  const queryParams: Record<string, any> = {};
+  if (payload?.startDate) {
+    queryParams.d = payload.startDate;
+  }
+  if (payload?.offset) {
+    queryParams.o = payload.offset;
+  }
+  if (payload?.count) {
+    queryParams.c = payload.count;
+  }
+  if (payload?.desiredAwardKinds) {
+    queryParams.k = payload.desiredAwardKinds.join(",");
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetRecentGameAwards.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetRecentGameAwardsResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/feed/getTopTenUsers.test.ts

@@ -22,7 +22,7 @@ describe("Function: getTopTenUsers", () => {
   it("retrieves metadata about the current top ten users on the site", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -51,48 +51,48 @@ describe("Function: getTopTenUsers", () => {
     // ASSERT
     expect(response).toEqual([
       {
-        userName: "MaxMilyin",
+        username: "MaxMilyin",
         totalPoints: 346_289,
         totalRatioPoints: 995_092,
       },
       {
-        userName: "HippopotamusRex",
+        username: "HippopotamusRex",
         totalPoints: 312_118,
         totalRatioPoints: 1_151_351,
       },
       {
-        userName: "Sarconius",
+        username: "Sarconius",
         totalPoints: 257_862,
         totalRatioPoints: 1_181_770,
       },
-      { userName: "guineu", totalPoints: 241_623, totalRatioPoints: 672_597 },
+      { username: "guineu", totalPoints: 241_623, totalRatioPoints: 672_597 },
       {
-        userName: "Andrey199650",
+        username: "Andrey199650",
         totalPoints: 240_101,
         totalRatioPoints: 567_522,
       },
       {
-        userName: "Wendigo",
+        username: "Wendigo",
         totalPoints: 227_903,
         totalRatioPoints: 1_099_685,
       },
       {
-        userName: "donutweegee",
+        username: "donutweegee",
         totalPoints: 204_701,
         totalRatioPoints: 587_221,
       },
       {
-        userName: "AmericanNinja",
+        username: "AmericanNinja",
         totalPoints: 202_980,
         totalRatioPoints: 567_618,
       },
       {
-        userName: "Infernum",
+        username: "Infernum",
         totalPoints: 202_171,
         totalRatioPoints: 689_967,
       },
       {
-        userName: "FabricioPrie",
+        username: "FabricioPrie",
         totalPoints: 196_974,
         totalRatioPoints: 450_436,
       },