@retroachievements/api 1.5.3 → 2.0.0

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

@@ -16,4 +16,12 @@ export interface GameInfoAndUserProgress extends GameExtended {
   numAwardedToUserHardcore: number;
   userCompletion: string;
   userCompletionHardcore: string;
+
+  highestAwardKind?:
+    | "mastered"
+    | "completed"
+    | "beaten-hardcore"
+    | "beaten-softcore"
+    | null;
+  highestAwardDate?: string;
 }

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

@@ -25,4 +25,12 @@ export interface GetGameInfoAndUserProgressResponse
   NumAwardedToUserHardcore: number;
   UserCompletion: string;
   UserCompletionHardcore: string;
+
+  HighestAwardKind?:
+    | "mastered"
+    | "completed"
+    | "beaten-hardcore"
+    | "beaten-softcore"
+    | null;
+  HighestAwardDate?: string;
 }

package/src/utils/internal/buildRequestUrl.test.ts

@@ -22,7 +22,7 @@ describe("Util: buildRequestUrl", () => {
     const requestUrl = buildRequestUrl(
       baseUrl,
       endpointUrl,
-      { userName: "TestUser", webApiKey: "mockWebApiKey" },
+      { username: "TestUser", webApiKey: "mockWebApiKey" },
       args as any
     );
 
@@ -39,7 +39,7 @@ describe("Util: buildRequestUrl", () => {
 
     // ACT
     const requestUrl = buildRequestUrl(baseUrl, endpointUrl, {
-      userName: "TestUser",
+      username: "TestUser",
       webApiKey: "mockWebApiKey",
     });
 

package/src/utils/internal/buildRequestUrl.ts

@@ -14,7 +14,7 @@ export const buildRequestUrl = (
   // `z` and `y` are expected query params from the RA API.
   // Authentication is handled purely by query params.
   const queryParamValues: Record<string, string> = {
-    z: authObject.userName,
+    z: authObject.username,
     y: authObject.webApiKey,
   };
 

package/src/utils/public/buildAuthorization.test.ts

@@ -9,7 +9,7 @@ describe("Util: buildAuthorization", () => {
   it("returns the same object it is given", () => {
     // ARRANGE
     const myAuth = {
-      userName: "myUserName",
+      username: "myUserName",
       webApiKey: "myWebApiKey",
     };
 
@@ -20,7 +20,7 @@ describe("Util: buildAuthorization", () => {
     expect(authorization).toEqual(myAuth);
   });
 
-  it("throws an error if missing a userName", () => {
+  it("throws an error if missing a username", () => {
     // ASSERT
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore - We're assuming the user is not using a TypeScript project.
@@ -31,6 +31,6 @@ describe("Util: buildAuthorization", () => {
     // ASSERT
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore - We're assuming the user is not using a TypeScript project.
-    expect(() => buildAuthorization({ userName: "mockUserName" })).toThrow();
+    expect(() => buildAuthorization({ username: "mockUserName" })).toThrow();
   });
 });

package/src/utils/public/buildAuthorization.ts

@@ -15,19 +15,19 @@ import type { AuthObject } from "./models";
  * @example
  * ```
  * const authorization = buildAuthorization({
- *   userName: "Scott",
+ *   username: "Scott",
  *   webApiKey: "LtjCwW16nJI7cqOyPIQtXk8v1cfF0tmO"
  * });
  * ```
  */
 export const buildAuthorization = (options: AuthObject): AuthObject => {
-  if (!options.userName || !options.webApiKey) {
+  if (!options.username || !options.webApiKey) {
     throw new Error(`
       buildAuthorization() requires an object containing a
-      userName and webApiKey. eg:
+      username and webApiKey. eg:
 
       const authorization = buildAuthorization({
-        userName: "myUserName",
+        username: "myUserName",
         webApiKey: "myWebApiKey"
       })
     `);

package/src/utils/public/models/auth-object.model.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

package/src/console/models/console-id.model.ts

@@ -1,5 +0,0 @@
-export interface ConsoleId {
-  id: number;
-  name: string;
-  iconUrl: string;
-}