@retroachievements/api 1.2.1 → 1.4.0

package/src/ticket/getTicketData.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -58,8 +58,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -136,8 +136,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -209,8 +209,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -258,8 +258,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -293,8 +293,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -327,8 +327,8 @@ describe("Function: getTicketData", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetTicketData.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetTicketData.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getAchievementsEarnedBetween.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -47,9 +47,8 @@ describe("Function: getAchievementsEarnedBetween", () => {
     ];
 
     server.use(
-      rest.get(
-        `${apiBaseUrl}/API_GetAchievementsEarnedBetween.php`,
-        (_, res, ctx) => res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetAchievementsEarnedBetween.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getAchievementsEarnedOnDay.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -47,9 +47,8 @@ describe("Function: getAchievementsEarnedOnDay", () => {
     ];
 
     server.use(
-      rest.get(
-        `${apiBaseUrl}/API_GetAchievementsEarnedOnDay.php`,
-        (_, res, ctx) => res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetAchievementsEarnedOnDay.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getGameInfoAndUserProgress.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable sonarjs/no-duplicate-string */
 
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -74,9 +74,8 @@ describe("Function: getGameInfoAndUserProgress", () => {
     };
 
     server.use(
-      rest.get(
-        `${apiBaseUrl}/API_GetGameInfoAndUserProgress.php`,
-        (_, res, ctx) => res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetGameInfoAndUserProgress.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserAwards.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -31,6 +31,8 @@ describe("Function: getUserAwards", () => {
       HiddenAwardsCount: 5,
       MasteryAwardsCount: 5,
       CompletionAwardsCount: 0,
+      BeatenHardcoreAwardsCount: 24,
+      BeatenSoftcoreAwardsCount: 7,
       EventAwardsCount: 0,
       SiteAwardsCount: 0,
       VisibleUserAwards: [
@@ -49,8 +51,8 @@ describe("Function: getUserAwards", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserAwards.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserAwards.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -63,6 +65,8 @@ describe("Function: getUserAwards", () => {
       hiddenAwardsCount: 5,
       masteryAwardsCount: 5,
       completionAwardsCount: 0,
+      beatenHardcoreAwardsCount: 24,
+      beatenSoftcoreAwardsCount: 7,
       eventAwardsCount: 0,
       siteAwardsCount: 0,
       visibleUserAwards: [

package/src/user/getUserAwards.ts

@@ -31,6 +31,8 @@ import type { GetUserAwardsResponse, UserAwards } from "./models";
  *   hiddenAwardsCount: 2,
  *   masteryAwardsCount: 6,
  *   completionAwardsCount: 0,
+ *   beatenHardcoreAwardsCount: 24,
+ *   beatenSoftcoreAwardsCount: 7,
  *   eventAwardsCount: 0,
  *   siteAwardsCount: 2,
  *   visibleUserAwards: [

package/src/user/getUserClaims.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable sonarjs/no-duplicate-string */
 
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -48,8 +48,8 @@ describe("Function: getUserClaims", () => {
     ];
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserClaims.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserClaims.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserCompletedGames.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable sonarjs/no-duplicate-string */
 
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -54,8 +54,8 @@ describe("Function: getUserCompletedGames", () => {
     ];
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserCompletedGames.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserCompletedGames.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserCompletionProgress.test.ts

@@ -0,0 +1,81 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserCompletionProgress } from "./getUserCompletionProgress";
+import type { GetUserCompletionProgressResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserCompletionProgress", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserCompletionProgress).toBeDefined();
+  });
+
+  it("retrieves completion progress by username", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserCompletionProgressResponse = {
+      Count: 1,
+      Total: 1,
+      Results: [
+        {
+          GameID: 680,
+          Title: "Game & Watch Gallery",
+          ImageIcon: "/Images/042952.png",
+          ConsoleID: 4,
+          ConsoleName: "Game Boy",
+          MaxPossible: 27,
+          NumAwarded: 8,
+          NumAwardedHardcore: 8,
+          MostRecentAwardedDate: "2022-07-26T23:56:15+00:00",
+          HighestAwardKind: null,
+          HighestAwardDate: null
+        }
+      ]
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUserCompletionProgress.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getUserCompletionProgress(authorization, {
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      count: 1,
+      total: 1,
+      results: [
+        {
+          gameId: 680,
+          title: "Game & Watch Gallery",
+          imageIcon: "/Images/042952.png",
+          consoleId: 4,
+          consoleName: "Game Boy",
+          maxPossible: 27,
+          numAwarded: 8,
+          numAwardedHardcore: 8,
+          mostRecentAwardedDate: "2022-07-26T23:56:15+00:00",
+          highestAwardKind: null,
+          highestAwardDate: null
+        }
+      ]
+    });
+  });
+});

package/src/user/getUserCompletionProgress.ts

@@ -0,0 +1,83 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserCompletionProgressResponse,
+  UserCompletionProgress
+} from "./models";
+
+/**
+ * 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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.userName The user for which to retrieve the progress for.
+ *
+ * @param payload.offset Defaults to 0. The number of entries to skip.
+ *
+ * @param payload.count Defaults to 100, has a max of 500.
+ *
+ * @example
+ * ```
+ * const userCompletionProgress = await getUserCompletionProgress(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns
+ * ```
+ * {
+ *   "count": 100,
+ *   "total": 752,
+ *   "results": [
+ *     {
+         gameId: 11406,
+         title: 'Mortal Kombat 4',
+         imageIcon: '/Images/042133.png',
+         consoleId: 12,
+         consoleName: 'PlayStation',
+         maxPossible: 131,
+         numAwarded: 131,
+         numAwardedHardcore: 131,
+         mostRecentAwardedDate: '2022-08-07T18:24:44+00:00',
+         highestAwardKind: 'mastered',
+         highestAwardDate: '2022-08-07T18:24:44+00:00'
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const getUserCompletionProgress = async (
+  authorization: AuthObject,
+  payload: { userName: string; offset?: number; count?: number }
+): Promise<UserCompletionProgress> => {
+  const { userName, offset, count } = payload;
+
+  const params: Record<string, string | number> = {
+    u: userName
+  };
+  if (offset) {
+    params["o"] = offset;
+  }
+  if (count) {
+    params["c"] = count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserCompletionProgress.php",
+    authorization,
+    params
+  );
+
+  const rawResponse = await call<GetUserCompletionProgressResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/user/getUserGameRankAndScore.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -36,8 +36,8 @@ describe("Function: getUserGameRankAndScore", () => {
     ];
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserGameRankAndScore.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserGameRankAndScore.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserPoints.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -32,8 +32,8 @@ describe("Function: getUserPoints", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserPoints.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserPoints.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserProfile.test.ts

@@ -0,0 +1,79 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserProfile } from "./getUserProfile";
+import type { GetUserProfileResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserProfile", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserProfile).toBeDefined();
+  });
+
+  it("given a username, retrieves minimal user profile information about the user", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserProfileResponse = {
+      User: "MaxMilyin",
+      UserPic: "/UserPic/MaxMilyin.png",
+      MemberSince: "2016-01-02 00:43:04",
+      RichPresenceMsg:
+        "Playing ~Hack~ 11th Annual Vanilla Level Design Contest, The",
+      LastGameID: 19_504,
+      ContribCount: 0,
+      ContribYield: 0,
+      TotalPoints: 399_597,
+      TotalSoftcorePoints: 0,
+      TotalTruePoints: 1_599_212,
+      Permissions: 1,
+      Untracked: 0,
+      ID: 16_446,
+      UserWallActive: 1,
+      Motto: "Join me on Twitch! GameSquadSquad for live RA"
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUserProfile.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getUserProfile(authorization, {
+      userName: "WCopeland"
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      user: "MaxMilyin",
+      userPic: "/UserPic/MaxMilyin.png",
+      memberSince: "2016-01-02 00:43:04",
+      richPresenceMsg:
+        "Playing ~Hack~ 11th Annual Vanilla Level Design Contest, The",
+      lastGameId: 19_504,
+      contribCount: 0,
+      contribYield: 0,
+      totalPoints: 399_597,
+      totalSoftcorePoints: 0,
+      totalTruePoints: 1_599_212,
+      permissions: 1,
+      untracked: false,
+      id: 16_446,
+      userWallActive: true,
+      motto: "Join me on Twitch! GameSquadSquad for live RA"
+    });
+  });
+});

package/src/user/getUserProfile.ts

@@ -0,0 +1,55 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.userName The user for which to retrieve the summary for.
+ *
+ * @example
+ * ```
+ * const userSummary = await getUserProfile(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing profile summary metadata about a target user.
+ */
+export const getUserProfile = async (
+  authorization: AuthObject,
+  payload: {
+    userName: string;
+  }
+): Promise<UserProfile> => {
+  const { userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserProfile.php",
+    authorization,
+    { u: userName }
+  );
+
+  const rawResponse = await call<GetUserProfileResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "TotalPoints",
+      "TotalSoftcorePoints",
+      "TotalTruePoints",
+      "Permissions"
+    ],
+    shouldMapToBooleans: ["Untracked", "UserWallActive"]
+  });
+};

package/src/user/getUserProgress.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -46,8 +46,8 @@ describe("Function: getUserProgress", () => {
     };
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserProgress.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserProgress.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserRecentAchievements.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -47,9 +47,8 @@ describe("Function: getUserRecentAchievements", () => {
     ];
 
     server.use(
-      rest.get(
-        `${apiBaseUrl}/API_GetUserRecentAchievements.php`,
-        (_, res, ctx) => res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserRecentAchievements.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserRecentlyPlayedGames.test.ts

@@ -1,4 +1,4 @@
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -45,9 +45,8 @@ describe("Function: getUserRecentlyPlayedGames", () => {
     ];
 
     server.use(
-      rest.get(
-        `${apiBaseUrl}/API_GetUserRecentlyPlayedGames.php`,
-        (_, res, ctx) => res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserRecentlyPlayedGames.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 

package/src/user/getUserSummary.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable sonarjs/no-duplicate-string */
 
-import { rest } from "msw";
+import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 
 import { apiBaseUrl } from "../utils/internal";
@@ -31,8 +31,8 @@ describe("Function: getUserSummary", () => {
     const mockResponse = mockGetUserSummaryResponse;
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserSummary.php`, (_, res, ctx) =>
-        res(ctx.json(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserSummary.php`, () =>
+        HttpResponse.json(mockResponse)
       )
     );
 
@@ -55,8 +55,8 @@ describe("Function: getUserSummary", () => {
     const mockResponse = "<html><body>the api is down</body></html>";
 
     server.use(
-      rest.get(`${apiBaseUrl}/API_GetUserSummary.php`, (_, res, ctx) =>
-        res(ctx.status(503), ctx.body(mockResponse))
+      http.get(`${apiBaseUrl}/API_GetUserSummary.php`, () =>
+        HttpResponse.json(mockResponse, { status: 503 })
       )
     );
 

package/src/user/getUserSummary.ts

@@ -17,7 +17,7 @@ import type { GetUserSummaryResponse, UserSummary } from "./models";
  * @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 5.
+ * This defaults to 0.
  *
  * @param payload.recentAchievementsCount Optional. The number of recent achievements
  * to return. This defaults to 5.
@@ -92,5 +92,3 @@ export const getUserSummary = async (
     ]
   });
 };
-
-// TODO: add test for this

package/src/user/index.ts

@@ -4,8 +4,10 @@ export * from "./getGameInfoAndUserProgress";
 export * from "./getUserAwards";
 export * from "./getUserClaims";
 export * from "./getUserCompletedGames";
+export * from "./getUserCompletionProgress";
 export * from "./getUserGameRankAndScore";
 export * from "./getUserPoints";
+export * from "./getUserProfile";
 export * from "./getUserProgress";
 export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";

package/src/user/models/award-type.model.ts

@@ -1,7 +1,8 @@
 export type AwardType =
-  | "Mastery/Completion"
-  | "Achievement Unlocks Yield"
   | "Achievement Points Yield"
-  | "Patreon Supporter"
+  | "Achievement Unlocks Yield"
   | "Certified Legend"
-  | "Invalid or deprecated award type";
+  | "Game Beaten"
+  | "Invalid or deprecated award type"
+  | "Mastery/Completion"
+  | "Patreon Supporter";