@retroachievements/api 1.5.3 → 2.1.0

package/src/user/getUserAwards.ts

@@ -11,16 +11,16 @@ import type { GetUserAwardsResponse, UserAwards } from "./models";
  * A call to this function will retrieve metadata about the target user's
  * site awards, via their 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 user for which to retrieve the site awards for.
+ * @param payload.username The user for which to retrieve the site awards for.
  *
  * @example
  * ```
  * const userAwards = await getUserAwards(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * )
  * ```
  *
@@ -53,11 +53,11 @@ import type { GetUserAwardsResponse, UserAwards } from "./models";
  */
 export const getUserAwards = async (
   authorization: AuthObject,
-  payload: { userName: string }
+  payload: { username: string }
 ): Promise<UserAwards> => {
-  const { userName } = payload;
+  const { username } = payload;
 
-  const queryParams: Record<string, string> = { u: userName };
+  const queryParams: Record<string, string> = { u: username };
 
   const url = buildRequestUrl(
     apiBaseUrl,

package/src/user/getUserClaims.test.ts

@@ -23,7 +23,7 @@ describe("Function: getUserClaims", () => {
 
   it("given a username, retrieves a list of achievement set claims for the user", async () => {
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -55,7 +55,7 @@ describe("Function: getUserClaims", () => {
 
     // ACT
     const response = await getUserClaims(authorization, {
-      userName: "Jamiras",
+      username: "Jamiras",
     });
 
     // ASSERT

package/src/user/getUserClaims.ts

@@ -12,17 +12,17 @@ import type { GetUserClaimsResponse, UserClaims } from "./models";
  * achievement set claims made over the lifetime of a given
  * user, targeted by their 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 user for which to retrieve the historical
+ * @param payload.username The user for which to retrieve the historical
  * achievement set claims list for.
  *
  * @example
  * ```
  * const userClaims = await getUserClaims(
  *   authorization,
- *   { userName: "Jamiras" }
+ *   { username: "Jamiras" }
  * );
  * ```
  *
@@ -31,15 +31,15 @@ import type { GetUserClaimsResponse, UserClaims } from "./models";
  */
 export const getUserClaims = async (
   authorization: AuthObject,
-  payload: { userName: string }
+  payload: { username: string }
 ): Promise<UserClaims> => {
-  const { userName } = payload;
+  const { username } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserClaims.php",
     authorization,
-    { u: userName }
+    { u: username }
   );
 
   const rawResponse = await call<GetUserClaimsResponse>({ url });

package/src/user/getUserCompletedGames.test.ts

@@ -24,7 +24,7 @@ describe("Function: getUserCompletedGames", () => {
   it("given a username, returns completion metadata", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -61,7 +61,7 @@ describe("Function: getUserCompletedGames", () => {
 
     // ACT
     const response = await getUserCompletedGames(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
     });
 
     // ASSERT

package/src/user/getUserCompletedGames.ts

@@ -17,17 +17,17 @@ import type {
  * one for the hardcore completion. These are designated by
  * the `hardcoreMode` property on each completion object.
  *
- * @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
  * completion metadata for.
  *
  * @example
  * ```
  * const userCompletedGames = await getUserCompletedGames(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -63,15 +63,15 @@ import type {
  */
 export const getUserCompletedGames = async (
   authorization: AuthObject,
-  payload: { userName: string }
+  payload: { username: string }
 ): Promise<UserCompletedGames> => {
-  const { userName } = payload;
+  const { username } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserCompletedGames.php",
     authorization,
-    { u: userName }
+    { u: username }
   );
 
   const rawResponse = await call<GetUserCompletedGamesResponse>({ url });

package/src/user/getUserCompletionProgress.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserCompletionProgress", () => {
   it("retrieves completion progress by username", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -54,7 +54,7 @@ describe("Function: getUserCompletionProgress", () => {
 
     // ACT
     const response = await getUserCompletionProgress(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
     });
 
     // ASSERT

package/src/user/getUserCompletionProgress.ts

@@ -14,10 +14,10 @@ import type {
  * A call to this function will retrieve a given user's completion
  * progress, targeted by their 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 user for which to retrieve the progress for.
+ * @param payload.username The user for which to retrieve the progress for.
  *
  * @param payload.offset Defaults to 0. The number of entries to skip.
  *
@@ -27,7 +27,7 @@ import type {
  * ```
  * const userCompletionProgress = await getUserCompletionProgress(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -56,12 +56,12 @@ import type {
  */
 export const getUserCompletionProgress = async (
   authorization: AuthObject,
-  payload: { userName: string; offset?: number; count?: number }
+  payload: { username: string; offset?: number; count?: number }
 ): Promise<UserCompletionProgress> => {
-  const { userName, offset, count } = payload;
+  const { username, offset, count } = payload;
 
   const params: Record<string, string | number> = {
-    u: userName,
+    u: username,
   };
   if (offset) {
     params["o"] = offset;

package/src/user/getUserGameRankAndScore.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserGameRankAndScore", () => {
   it("given a game ID and a user name, retrieves metadata about how that user ranks on the given game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -43,7 +43,7 @@ describe("Function: getUserGameRankAndScore", () => {
 
     // ACT
     const response = await getUserGameRankAndScore(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
       gameId: 14_402,
     });
 

package/src/user/getUserGameRankAndScore.ts

@@ -16,7 +16,7 @@ import type {
  * how a particular user has performed/ranked on a particular
  * 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
@@ -24,14 +24,14 @@ 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 ranking metadata for.
  *
  * @example
  * ```
  * const userGameRankAndScore = await getUserGameRankAndScore(
  *   authorization,
- *   { gameId: 14402, userName: "xelnia" }
+ *   { gameId: 14402, username: "xelnia" }
  * );
  * ```
  *
@@ -51,15 +51,15 @@ import type {
  */
 export const getUserGameRankAndScore = async (
   authorization: AuthObject,
-  payload: { gameId: ID; userName: string }
+  payload: { gameId: ID; username: string }
 ): Promise<UserGameRankAndScore> => {
-  const { gameId, userName } = payload;
+  const { gameId, username } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserGameRankAndScore.php",
     authorization,
-    { g: gameId, u: userName }
+    { g: gameId, u: username }
   );
 
   const rawResponse = await call<GetUserGameRankAndScoreResponse>({ url });

package/src/user/getUserPoints.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserPoints", () => {
   it("given a username, retrieves the point values associated with the user", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -38,7 +38,7 @@ describe("Function: getUserPoints", () => {
     );
 
     // ACT
-    const response = await getUserPoints(authorization, { userName: "xelnia" });
+    const response = await getUserPoints(authorization, { username: "xelnia" });
 
     // ASSERT
     expect(response).toEqual({

package/src/user/getUserPoints.ts

@@ -11,16 +11,16 @@ import type { GetUserPointsResponse, UserPoints } from "./models";
  * A call to this function will retrieve a given user's hardcore
  * and softcore points.
  *
- * @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 point totals for.
+ * @param payload.username The user for which to retrieve the point totals for.
  *
  * @example
  * ```
  * const userPoints = await getUserPoints(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -34,15 +34,15 @@ import type { GetUserPointsResponse, UserPoints } from "./models";
  */
 export const getUserPoints = async (
   authorization: AuthObject,
-  payload: { userName: string }
+  payload: { username: string }
 ): Promise<UserPoints> => {
-  const { userName } = payload;
+  const { username } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserPoints.php",
     authorization,
-    { u: userName }
+    { u: username }
   );
 
   const rawResponse = await call<GetUserPointsResponse>({ url });

package/src/user/getUserProfile.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserProfile", () => {
   it("given a username, retrieves minimal user profile information about the user", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -53,7 +53,7 @@ describe("Function: getUserProfile", () => {
 
     // ACT
     const response = await getUserProfile(authorization, {
-      userName: "WCopeland",
+      username: "WCopeland",
     });
 
     // ASSERT

package/src/user/getUserProfile.ts

@@ -11,16 +11,16 @@ import type { GetUserProfileResponse, UserProfile } from "./models";
  * A call to this function will retrieve summary information about
  * a given user, targeted by 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 user for which to retrieve the summary for.
+ * @param payload.username The user for which to retrieve the summary for.
  *
  * @example
  * ```
  * const userSummary = await getUserProfile(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -29,16 +29,16 @@ import type { GetUserProfileResponse, UserProfile } from "./models";
 export const getUserProfile = async (
   authorization: AuthObject,
   payload: {
-    userName: string;
+    username: string;
   }
 ): Promise<UserProfile> => {
-  const { userName } = payload;
+  const { username } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserProfile.php",
     authorization,
-    { u: userName }
+    { u: username }
   );
 
   const rawResponse = await call<GetUserProfileResponse>({ url });

package/src/user/getUserProgress.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserProgress", () => {
   it(`retrieves a map of a user's progress by game IDs`, async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -53,7 +53,7 @@ describe("Function: getUserProgress", () => {
 
     // ACT
     const response = await getUserProgress(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
       gameIds: [1, 14_402],
     });
 

package/src/user/getUserProgress.ts

@@ -12,10 +12,10 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
  * A call to this function will retrieve a given user's
  * progress on a given list of games, 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.userName The user for which to retrieve the progress for.
+ * @param payload.username The user for which to retrieve the progress for.
  *
  * @param payload.gameIds An array of RetroAchievements game IDs. If you aren't
  * sure of the game ID, visit the game's page on the website and copy the number
@@ -25,7 +25,7 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
  * ```
  * const userProgress = await getUserProgress(
  *   authorization,
- *   { userName: "xelnia", gameIds: [1, 14402] }
+ *   { username: "xelnia", gameIds: [1, 14402] }
  * );
  * ```
  *
@@ -53,15 +53,15 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
  */
 export const getUserProgress = async (
   authorization: AuthObject,
-  payload: { userName: string; gameIds: ID[] }
+  payload: { username: string; gameIds: ID[] }
 ): Promise<UserProgress> => {
-  const { userName, gameIds } = payload;
+  const { username, gameIds } = payload;
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetUserProgress.php",
     authorization,
-    { u: userName, i: gameIds.join(",") }
+    { u: username, i: gameIds.join(",") }
   );
 
   const rawResponse = await call<GetUserProgressResponse>({ url });

package/src/user/getUserRecentAchievements.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserRecentAchievements", () => {
   it("retrieves a list of recently-earned user achievements", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -54,7 +54,7 @@ describe("Function: getUserRecentAchievements", () => {
 
     // ACT
     const response = await getUserRecentAchievements(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
     });
 
     // ASSERT

package/src/user/getUserRecentAchievements.ts

@@ -15,10 +15,10 @@ import type {
  * recently earned achievements, via their username. By default, it
  * fetches achievements earned in the last hour.
  *
- * @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 recent achievements for.
+ * @param payload.username The user for which to retrieve the recent achievements for.
  *
  * @param payload.recentMinutes Optional. Defaults to 60. How many minutes
  * back to fetch for the given user.
@@ -27,7 +27,7 @@ import type {
  * ```
  * const userRecentAchievements = await getUserRecentAchievements(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -55,11 +55,11 @@ import type {
  */
 export const getUserRecentAchievements = async (
   authorization: AuthObject,
-  payload: { userName: string; recentMinutes?: number }
+  payload: { username: string; recentMinutes?: number }
 ): Promise<UserRecentAchievement[]> => {
-  const { userName, recentMinutes } = payload;
+  const { username, recentMinutes } = payload;
 
-  const queryParams: Record<string, string | number> = { u: userName };
+  const queryParams: Record<string, string | number> = { u: username };
 
   if (recentMinutes !== undefined) {
     queryParams["m"] = recentMinutes;

package/src/user/getUserRecentlyPlayedGames.test.ts

@@ -22,7 +22,7 @@ describe("Function: getUserRecentlyPlayedGames", () => {
   it(`retrieves a list of a given user's recently played games`, async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -52,7 +52,7 @@ describe("Function: getUserRecentlyPlayedGames", () => {
 
     // ACT
     const response = await getUserRecentlyPlayedGames(authorization, {
-      userName: "xelnia",
+      username: "xelnia",
     });
 
     // ASSERT

package/src/user/getUserRecentlyPlayedGames.ts

@@ -14,10 +14,10 @@ import type {
  * A call to this function will retrieve a list of a target user's
  * recently played games, via their 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 user for which to retrieve the summary for.
+ * @param payload.username The user for which to retrieve the summary for.
  *
  * @param payload.count Optional. Defaults to 10. Max is 50. How many
  * recently played games for the user to retrieve.
@@ -29,7 +29,7 @@ import type {
  * ```
  * const userRecentlyPlayedGames = await getUserRecentlyPlayedGames(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -55,11 +55,11 @@ import type {
  */
 export const getUserRecentlyPlayedGames = async (
   authorization: AuthObject,
-  payload: { userName: string; offset?: number; count?: number }
+  payload: { username: string; offset?: number; count?: number }
 ): Promise<UserRecentlyPlayedGames> => {
-  const { userName, offset, count } = payload;
+  const { username, offset, count } = payload;
 
-  const queryParams: Record<string, string | number> = { u: userName };
+  const queryParams: Record<string, string | number> = { u: username };
 
   if (offset !== undefined) {
     queryParams["o"] = offset;

package/src/user/getUserSummary.test.ts

@@ -24,7 +24,7 @@ describe("Function: getUserSummary", () => {
   it("given a username, retrieves user summary information about the user", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -38,7 +38,7 @@ describe("Function: getUserSummary", () => {
 
     // ACT
     const response = await getUserSummary(authorization, {
-      userName: "WCopeland",
+      username: "WCopeland",
     });
 
     // ASSERT
@@ -48,7 +48,7 @@ describe("Function: getUserSummary", () => {
   it("given the API returns a 503, throws an error", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
-      userName: "mockUserName",
+      username: "mockUserName",
       webApiKey: "mockWebApiKey",
     });
 
@@ -62,7 +62,7 @@ describe("Function: getUserSummary", () => {
 
     // ASSERT
     await expect(
-      getUserSummary(authorization, { userName: "WCopeland" })
+      getUserSummary(authorization, { username: "WCopeland" })
     ).rejects.toThrow();
   });
 });

package/src/user/getUserSummary.ts

@@ -11,10 +11,10 @@ import type { GetUserSummaryResponse, UserSummary } from "./models";
  * A call to this function will retrieve summary information about
  * a given user, targeted by 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 user for which to retrieve the summary for.
+ * @param payload.username The user for which to retrieve the summary for.
  *
  * @param payload.recentGamesCount Optional. The number of recent games to return.
  * This defaults to 0.
@@ -26,7 +26,7 @@ import type { GetUserSummaryResponse, UserSummary } from "./models";
  * ```
  * const userSummary = await getUserSummary(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { username: "xelnia" }
  * );
  * ```
  *
@@ -35,14 +35,14 @@ import type { GetUserSummaryResponse, UserSummary } from "./models";
 export const getUserSummary = async (
   authorization: AuthObject,
   payload: {
-    userName: string;
+    username: string;
     recentGamesCount?: number;
     recentAchievementsCount?: number;
   }
 ): Promise<UserSummary> => {
-  const { userName, recentGamesCount, recentAchievementsCount } = payload;
+  const { username, recentGamesCount, recentAchievementsCount } = payload;
 
-  const queryParams: Record<string, string | number> = { u: userName };
+  const queryParams: Record<string, string | number> = { u: username };
 
   if (recentGamesCount !== undefined) {
     queryParams["g"] = recentGamesCount;

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

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