@retroachievements/api 1.5.3 → 2.0.0

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/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,
       },

package/src/feed/getTopTenUsers.ts

@@ -10,7 +10,7 @@ import type {
  * A call to this function will retrieve the current top ten users
  * on the site.
  *
- * @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
@@ -21,8 +21,8 @@ import type {
  * @returns An array containing the list of top ten users.
  * ```json
  * [
- *   { userName: "MockUser", totalPoints: 350000, totalRatioPoints: 995000 },
- *   { userName: "MockUser2", totalPoints: 345000, totalRatioPoints: 994000 },
+ *   { username: "MockUser", totalPoints: 350000, totalRatioPoints: 995000 },
+ *   { username: "MockUser2", totalPoints: 345000, totalRatioPoints: 994000 },
  *   // ...
  * ]
  * ```
@@ -41,7 +41,7 @@ export const getTopTenUsers = async (
   const sanitizedTopTenUsers: TopTenUsersEntity[] = [];
   for (const rawUser of rawTopTenUsers) {
     sanitizedTopTenUsers.push({
-      userName: rawUser["1"],
+      username: rawUser["1"],
       totalPoints: Number(rawUser["2"]),
       totalRatioPoints: Number(rawUser["3"]),
     });

package/src/feed/models/top-ten-users-entity.model.ts

@@ -1,5 +1,5 @@
 export interface TopTenUsersEntity {
-  userName: string;
+  username: string;
   totalPoints: number;
   totalRatioPoints: number;
 }

package/src/game/getAchievementCount.test.ts

@@ -22,7 +22,7 @@ describe("Function: getAchievementCount", () => {
   it("given a game ID, retrieves the list of achievement IDs associated with the game and cleans properties", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getAchievementCount.ts

@@ -12,7 +12,7 @@ import type { AchievementCount, GetAchievementCountResponse } from "./models";
  * A call to this function will retrieve the list of
  * achievement IDs for a game, targeted by game 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.gameId The unique game ID. If you are unsure, open the

package/src/game/getAchievementDistribution.test.ts

@@ -23,7 +23,7 @@ describe("Function: getAchievementDistribution", () => {
   it("given a game ID, retrieves the achievement distribution associated with the game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -61,7 +61,7 @@ describe("Function: getAchievementDistribution", () => {
   it("given flags, successfully attaches the option to the call", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -101,7 +101,7 @@ describe("Function: getAchievementDistribution", () => {
   it("given a truthy hardcore value, successfully attaches the option to the call", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -138,7 +138,7 @@ describe("Function: getAchievementDistribution", () => {
   it("given a falsy hardcore value, successfully attaches the option to the call", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getAchievementDistribution.ts

@@ -11,7 +11,7 @@ import type {
  * of the number of players who have earned a specific
  * number of achievements for a given game 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.gameId The unique game ID. If you are unsure, open the

package/src/game/getGame.test.ts

@@ -24,7 +24,7 @@ describe("Function: getGame", () => {
   it("given a game ID, retrieves basic metadata about the game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getGame.ts

@@ -12,7 +12,7 @@ import type { Game, GetGameResponse } from "./models";
  * A call to this function will retrieve basic metadata about
  * a game, targeted via its unique 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.gameId The unique game ID. If you are unsure, open the

package/src/game/getGameExtended.test.ts

@@ -24,7 +24,7 @@ describe("Function: getGameExtended", () => {
   it("given a game ID, retrieves extended metadata about the game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getGameExtended.ts

@@ -12,7 +12,7 @@ import type { GameExtended, GetGameExtendedResponse } from "./models";
  * A call to this function will retrieve extended metadata
  * about a game, targeted via its unique 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.gameId The unique game ID. If you are unsure, open the

package/src/game/getGameRankAndScore.test.ts

@@ -24,7 +24,7 @@ describe("Function: getGameRankAndScore", () => {
   it("given a game ID, retrieves metadata about latest masteries for a game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getGameRankAndScore.ts

@@ -17,7 +17,7 @@ import type {
  * points earners for a game. The game is targeted via
  * its unique 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.gameId The unique game ID. If you are unsure, open the

package/src/game/getGameRating.test.ts

@@ -22,7 +22,7 @@ describe("Function: getGameRating", () => {
   it("given a game ID, retrieves metadata about how users have rated it", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 

package/src/game/getGameRating.ts

@@ -12,7 +12,7 @@ import type { GameRating, GetGameRatingResponse } from "./models";
  * A call to this function will retrieve metadata about
  * how users have rated the game and its set.
  *
- * @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.gameId The unique game ID. If you are unsure, open the

package/src/ticket/getTicketData.test.ts

@@ -28,7 +28,7 @@ describe("Function: getTicketData", () => {
   it("given only a ticket ID, retrieves ticket data", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -96,7 +96,7 @@ describe("Function: getTicketData", () => {
   it("given no IDs, retrieves a list of recent tickets", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -184,7 +184,7 @@ describe("Function: getTicketData", () => {
   it("can retrieve a list of the most ticketed games", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -244,7 +244,7 @@ describe("Function: getTicketData", () => {
   it("can retrieve metadata about a user's tickets", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -264,7 +264,7 @@ describe("Function: getTicketData", () => {
     );
 
     // ACT
-    const response = await getTicketData(authorization, { userName: "xelnia" });
+    const response = await getTicketData(authorization, { username: "xelnia" });
 
     // ASSERT
     expect(response).toEqual({
@@ -280,7 +280,7 @@ describe("Function: getTicketData", () => {
   it("can retrieve metadata about a game's tickets", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -314,7 +314,7 @@ describe("Function: getTicketData", () => {
   it("can retrieve metadata about an achievement's tickets", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });