@retroachievements/api 1.5.3 → 2.1.0

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/index.ts

@@ -1,5 +1,6 @@
 export * from "./getAchievementOfTheWeek";
 export * from "./getActiveClaims";
 export * from "./getClaims";
+export * from "./getRecentGameAwards";
 export * from "./getTopTenUsers";
 export * from "./models";

package/src/feed/models/get-recent-game-awards-response.model.ts

@@ -0,0 +1,15 @@
+import type { AwardKind } from "../../utils/public";
+
+export interface GetRecentGameAwardsResponse {
+  Count: number;
+  Total: number;
+  Results: Array<{
+    User: string;
+    AwardKind: AwardKind;
+    AwardDate: string;
+    GameID: number;
+    GameTitle: string;
+    ConsoleID: number;
+    ConsoleName: string;
+  }>;
+}

package/src/feed/models/index.ts

@@ -3,8 +3,10 @@ export * from "./claim-set-type.enum";
 export * from "./claim-status.enum";
 export * from "./claim-type.enum";
 export * from "./get-achievement-of-the-week-response.model";
+export * from "./get-recent-game-awards-response.model";
 export * from "./get-set-claims-response.model";
 export * from "./get-top-ten-users-response.model";
+export * from "./recent-game-awards.model";
 export * from "./set-claim.model";
 export * from "./top-ten-users.model";
 export * from "./top-ten-users-entity.model";

package/src/feed/models/recent-game-awards.model.ts

@@ -0,0 +1,15 @@
+import type { AwardKind } from "../../utils/public";
+
+export interface RecentGameAwards {
+  count: number;
+  total: number;
+  results: Array<{
+    user: string;
+    awardKind: AwardKind;
+    awardDate: string;
+    gameId: number;
+    gameTitle: string;
+    consoleId: number;
+    consoleName: string;
+  }>;
+}

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",
     });
 

package/src/ticket/getTicketData.ts

@@ -20,7 +20,7 @@ interface GetTicketDataAllPayloadValues {
   offset?: number;
   count?: number;
   isGettingMostTicketedGames?: true;
-  userName?: string;
+  username?: string;
   gameId?: string | number;
   isGettingTicketsForUnofficialAchievements?: true;
   shouldReturnTicketsList?: true;
@@ -35,7 +35,7 @@ interface GetTicketDataAllPayloadValues {
  * A call to this function will retrieve ticket metadata information
  * about a single achievement ticket, targeted by its ticket 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.ticketId The ID of the ticket to get information about.
@@ -59,7 +59,7 @@ export function getTicketData(
  * A call to this function will retrieve ticket metadata information
  * about the latest opened achievement tickets on RetroAchievements.
  *
- * @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.count Optional. Defaults to 10. Max is 100.
@@ -84,7 +84,7 @@ export function getTicketData(
  * A call to this function will retrieve the games on the site with
  * the highest count of opened achievement tickets.
  *
- * @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.count Optional. Defaults to 10. Max is 100.
@@ -112,17 +112,17 @@ export function getTicketData(
  * A call to this function will retrieve an achievement developer's
  * ticket stats, targeted by that developer's username.
  *
- * @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.userName The developer's account username to retrieve
+ * @param payload.username The developer's account username to retrieve
  * ticket stats for.
  *
  * @example
  * ```
  * const ticketData = await getTicketData(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -130,7 +130,7 @@ export function getTicketData(
  */
 export function getTicketData(
   authorization: AuthObject,
-  payload: { userName: string }
+  payload: { username: string }
 ): Promise<UserTicketStats>;
 
 /**
@@ -138,7 +138,7 @@ export function getTicketData(
  * by the game's ID. If you are unsure of a game's ID, visit its page
  * on the RetroAchievements website and copy the number at the end of the URL.
  *
- * @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 game ID to fetch ticket stats for.
@@ -174,7 +174,7 @@ export function getTicketData(
  * of an achievement's ID, open its page on the RetroAchievements
  * website and copy the number at the end of the URL.
  *
- * @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 ID of the achievement to fetch ticket
@@ -234,7 +234,7 @@ const buildGetTicketDataQueryParams = (
   const {
     ticketId,
     isGettingMostTicketedGames,
-    userName,
+    username,
     gameId,
     isGettingTicketsForUnofficialAchievements,
     shouldReturnTicketsList,
@@ -248,8 +248,8 @@ const buildGetTicketDataQueryParams = (
   } else if (isGettingMostTicketedGames) {
     queryParams["f"] = "1";
     queryParams = applyPaginationQueryParams(queryParams, payload);
-  } else if (userName) {
-    queryParams["u"] = userName;
+  } else if (username) {
+    queryParams["u"] = username;
   } else if (gameId) {
     queryParams["g"] = gameId;
 

package/src/user/getAchievementsEarnedBetween.test.ts

@@ -25,7 +25,7 @@ describe("Function: getAchievementsEarnedBetween", () => {
   it("retrieves a list of user achievements earned between a set of dates", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -58,7 +58,7 @@ describe("Function: getAchievementsEarnedBetween", () => {
 
     // ACT
     const response = await getAchievementsEarnedBetween(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
       fromDate: new Date("2022-10-12"),
       toDate: new Date("2022-10-13"),
     });

package/src/user/getAchievementsEarnedBetween.ts

@@ -14,10 +14,10 @@ import type {
  * A call to this function will retrieve a list of achievements
  * earned by a given user between two provided dates.
  *
- * @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.userName The user for which to retrieve the
+ * @param payload.username The user for which to retrieve the
  * list of achievements for.
  *
  * @param payload.fromDate A Date object specifying when
@@ -31,7 +31,7 @@ import type {
  * const achievementsEarnedBetween = await getAchievementsEarnedBetween(
  *   authorization,
  *   {
- *     userName: "xelnia",
+ *     username: "xelnia",
  *     fromDate: new Date("2022-10-12"),
  *     toDate: new Date("2022-10-13")
  *   }
@@ -65,16 +65,16 @@ import type {
  */
 export const getAchievementsEarnedBetween = async (
   authorization: AuthObject,
-  payload: { userName: string; fromDate: Date; toDate: Date }
+  payload: { username: string; fromDate: Date; toDate: Date }
 ): Promise<DatedUserAchievement[]> => {
-  const { userName, fromDate, toDate } = payload;
+  const { username, fromDate, toDate } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetAchievementsEarnedBetween.php",
     authorization,
     {
-      u: userName,
+      u: username,
       f: (fromDate.getTime() / 1000).toFixed(0),
       t: (toDate.getTime() / 1000).toFixed(0),
     }

package/src/user/getAchievementsEarnedOnDay.test.ts

@@ -25,7 +25,7 @@ describe("Function: getAchievementsEarnedOnDay", () => {
   it("retrieves a list of user achievements earned on a specified date", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -58,7 +58,7 @@ describe("Function: getAchievementsEarnedOnDay", () => {
 
     // ACT
     const response = await getAchievementsEarnedOnDay(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
       onDate: new Date("2022-10-12"),
     });
 

package/src/user/getAchievementsEarnedOnDay.ts

@@ -14,10 +14,10 @@ import type {
  * A call to this function will retrieve a list of achievements
  * earned by a given user on a specified date.
  *
- * @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.userName The user for which to retrieve the
+ * @param payload.username The user for which to retrieve the
  * list of achievements for.
  *
  * @param payload.fromDate A Date object specifying when
@@ -31,7 +31,7 @@ import type {
  * const achievementsEarnedOnDay = await getAchievementsEarnedOnDay(
  *   authorization,
  *   {
- *     userName: "xelnia",
+ *     username: "xelnia",
  *     onDate: new Date("2022-10-13")
  *   }
  * );
@@ -64,16 +64,16 @@ import type {
  */
 export const getAchievementsEarnedOnDay = async (
   authorization: AuthObject,
-  payload: { userName: string; onDate: Date }
+  payload: { username: string; onDate: Date }
 ): Promise<DatedUserAchievement[]> => {
-  const { userName, onDate } = payload;
+  const { username, onDate } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetAchievementsEarnedOnDay.php",
     authorization,
     {
-      u: userName,
+      u: username,
       // YYYY-MM-DD
       d: `${onDate.getFullYear()}-${onDate.getMonth() + 1}-${onDate.getDate()}`,
     }

package/src/user/getGameInfoAndUserProgress.test.ts

@@ -24,7 +24,7 @@ describe("Function: getGameInfoAndUserProgress", () => {
   it("given a game ID and a username, retrieves extended metadata about the game and that user`s progress", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -82,7 +82,7 @@ describe("Function: getGameInfoAndUserProgress", () => {
     // ACT
     const response = await getGameInfoAndUserProgress(authorization, {
       gameId: 14_402,
-      userName: "xelnia",
+      username: "xelnia",
     });
 
     // ASSERT
@@ -99,7 +99,7 @@ describe("Function: getGameInfoAndUserProgress", () => {
       publisher: "Activision ",
       developer: "David Crane",
       genre: "Racing",
-      released: 1980,
+      released: "1980",
       isFinal: false,
       consoleName: "Atari 2600",
       richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",

package/src/user/getGameInfoAndUserProgress.ts

@@ -16,7 +16,7 @@ import type {
  * about a game, in addition to a user's progress about a game.
  * This is targeted via a game's unique ID and a given username.
  *
- * @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
@@ -24,14 +24,17 @@ import type {
  * URL is https://retroachievements.org/game/14402. We can see from the
  * URL that the game ID is "14402".
  *
- * @param payload.userName The user for which to retrieve the
+ * @param payload.username The user for which to retrieve the
  * game progress for.
  *
+ * @param payload.shouldIncludeHighestAwardMetadata Include a "HighestAwardKind"
+ * and a "HighestAwardDate" for the given user and game ID.
+ *
  * @example
  * ```
  * const gameInfoAndUserProgress = await getGameInfoAndUserProgress(
  *   authorization,
- *   { gameId: 14402, userName: "wv_pinball" }
+ *   { gameId: 14402, username: "wv_pinball" }
  * );
  * ```
  *
@@ -51,7 +54,7 @@ import type {
  *   publisher: "Activision",
  *   developer: "David Crane",
  *   genre: "Racing",
- *   released: 1980,
+ *   released: "1980",
  *   isFinal: false,
  *   consoleName: "Atari 2600",
  *   richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
@@ -87,18 +90,27 @@ import type {
  */
 export const getGameInfoAndUserProgress = async (
   authorization: AuthObject,
-  payload: { gameId: ID; userName: string }
+  payload: {
+    gameId: ID;
+    username: string;
+    shouldIncludeHighestAwardMetadata?: boolean;
+  }
 ): Promise<GameInfoAndUserProgress> => {
-  const { gameId, userName } = payload;
+  const { gameId, username, shouldIncludeHighestAwardMetadata } = payload;
+
+  const params: Record<string, any> = {
+    g: gameId,
+    u: username,
+  };
+  if (shouldIncludeHighestAwardMetadata) {
+    params.a = 1;
+  }
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetGameInfoAndUserProgress.php",
     authorization,
-    {
-      g: gameId,
-      u: userName,
-    }
+    params
   );
 
   const rawResponse = await call<GetGameInfoAndUserProgressResponse>({ url });
@@ -113,7 +125,6 @@ export const getGameInfoAndUserProgress = async (
       "DisplayOrder",
       "NumDistinctPlayersCasual",
       "NumDistinctPlayersHardcore",
-      "Released",
     ],
   });
 };

package/src/user/getUserAwards.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserAwards", () => {
   it("retrieves a list of a target user awards", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -57,7 +57,7 @@ describe("Function: getUserAwards", () => {
     );
 
     // ACT
-    const response = await getUserAwards(authorization, { userName: "xelnia" });
+    const response = await getUserAwards(authorization, { username: "xelnia" });
 
     // ASSERT
     expect(response).toEqual({