@retroachievements/api 0.0.0-development

package/src/user/getUserProgress.test.ts

@@ -0,0 +1,80 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserProgress } from "./getUserProgress";
+import type { GetUserProgressResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserProgress", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserProgress).toBeDefined();
+  });
+
+  it(`retrieves a map of a user's progress by game IDs`, async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserProgressResponse = {
+      "1": {
+        NumPossibleAchievements: "10",
+        PossibleScore: "200",
+        NumAchieved: "4",
+        ScoreAchieved: "80",
+        NumAchievedHardcore: "4",
+        ScoreAchievedHardcore: "80"
+      },
+      "14402": {
+        NumPossibleAchievements: "10",
+        PossibleScore: "200",
+        NumAchieved: "4",
+        ScoreAchieved: "80",
+        NumAchievedHardcore: "4",
+        ScoreAchievedHardcore: "80"
+      }
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserProgress.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserProgress(authorization, {
+      userName: "xelnia",
+      gameIds: [1, 14_402]
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      "1": {
+        numPossibleAchievements: 10,
+        possibleScore: 200,
+        numAchieved: 4,
+        scoreAchieved: 80,
+        numAchievedHardcore: 4,
+        scoreAchievedHardcore: 80
+      },
+      "14402": {
+        numPossibleAchievements: 10,
+        possibleScore: 200,
+        numAchieved: 4,
+        scoreAchieved: 80,
+        numAchievedHardcore: 4,
+        scoreAchievedHardcore: 80
+      }
+    });
+  });
+});

package/src/user/getUserProgress.ts

@@ -0,0 +1,78 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GetUserProgressResponse, UserProgress } from "./models";
+
+/**
+ * A call to this function will retrieve a given user's
+ * progress on a given set of games, targeted by game ID.
+ *
+ * @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.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
+ * at the end of the URL.
+ *
+ * @example
+ * ```
+ * const userProgress = await getUserProgress(
+ *   authorization,
+ *   { userName: "xelnia", gameIds: [14402, 1] }
+ * );
+ * ```
+ *
+ * @returns An object which is a map of summarized progress for games.
+ * ```json
+ * {
+ *   "1": {
+ *     numPossibleAchievements: 24,
+ *     possibleScore: 255,
+ *     numAchieved: 0,
+ *     scoreAchieved: 0,
+ *     numAchievedHardcore: 0,
+ *     scoreAchievedHardcore: 0
+ *   },
+ *   "14402": {
+ *     numPossibleAchievements: 24,
+ *     possibleScore: 255,
+ *     numAchieved: 0,
+ *     scoreAchieved: 0,
+ *     numAchievedHardcore: 0,
+ *     scoreAchievedHardcore: 0
+ *   }
+ * }
+ * ```
+ */
+export const getUserProgress = async (
+  authorization: AuthObject,
+  payload: { userName: string; gameIds: Array<number | string> }
+): Promise<UserProgress> => {
+  const { userName, gameIds } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserProgress.php",
+    authorization,
+    { u: userName, i: gameIds.join(",") }
+  );
+
+  const rawResponse = await call<GetUserProgressResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "NumPossibleAchievements",
+      "PossibleScore",
+      "NumAchieved",
+      "ScoreAchieved",
+      "NumAchievedHardcore",
+      "ScoreAchievedHardcore"
+    ]
+  });
+};

package/src/user/getUserRecentlyPlayedGames.test.ts

@@ -0,0 +1,76 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserRecentlyPlayedGames } from "./getUserRecentlyPlayedGames";
+import type { GetUserRecentlyPlayedGamesResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserRecentlyPlayedGames", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserRecentlyPlayedGames).toBeDefined();
+  });
+
+  it(`retrieves a list of a given user's recently played games`, async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserRecentlyPlayedGamesResponse = [
+      {
+        GameID: "6278",
+        ConsoleID: "12",
+        ConsoleName: "PlayStation",
+        Title: "Duke Nukem: Land of the Babes",
+        ImageIcon: "/Images/054546.png",
+        LastPlayed: "2022-11-06 16:08:21",
+        NumPossibleAchievements: "42",
+        PossibleScore: "478",
+        NumAchieved: 0,
+        ScoreAchieved: 0,
+        NumAchievedHardcore: 0,
+        ScoreAchievedHardcore: 0
+      }
+    ];
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetUserRecentlyPlayedGames.php`,
+        (_, res, ctx) => res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserRecentlyPlayedGames(authorization, {
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        gameId: 6278,
+        consoleId: 12,
+        consoleName: "PlayStation",
+        title: "Duke Nukem: Land of the Babes",
+        imageIcon: "/Images/054546.png",
+        lastPlayed: "2022-11-06 16:08:21",
+        numPossibleAchievements: 42,
+        possibleScore: 478,
+        numAchieved: 0,
+        scoreAchieved: 0,
+        numAchievedHardcore: 0,
+        scoreAchievedHardcore: 0
+      }
+    ]);
+  });
+});

package/src/user/getUserRecentlyPlayedGames.ts

@@ -0,0 +1,93 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserRecentlyPlayedGamesResponse,
+  UserRecentlyPlayedGames
+} from "./models";
+
+/**
+ * A call to this function will retrieve a list of a target user's
+ * recently played games, 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.
+ *
+ * @param payload.count Optional. Defaults to 10. Max is 50. How many
+ * recently played games for the user to retrieve.
+ *
+ * @param payload.offset Optional. Defaults to 0. Number of recently played
+ * game entries to skip. This can be used for pagination.
+ *
+ * @example
+ * ```
+ * const userRecentlyPlayedGames = await getUserRecentlyPlayedGames(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about a user's recently played games.
+ * ```json
+ * [
+ *   {
+ *     gameId: 19010,
+ *     consoleId: 21,
+ *     consoleName: "PlayStation 2",
+ *     title: "Simpsons, The: Hit & Run",
+ *     imageIcon: "/Images/066024.png",
+ *     lastPlayed: "2022-10-24 22:05:12",
+ *     numPossibleAchievements: 131,
+ *     possibleScore: 865,
+ *     numAchieved: 23,
+ *     scoreAchieved: 84,
+ *     numAchievedHardcore: 23,
+ *     scoreAchievedHardcore: 84
+ *   }
+ * ]
+ * ```
+ */
+export const getUserRecentlyPlayedGames = async (
+  authorization: AuthObject,
+  payload: { userName: string; offset?: number; count?: number }
+): Promise<UserRecentlyPlayedGames> => {
+  const { userName, offset, count } = payload;
+
+  const queryParams: Record<string, string | number> = { u: userName };
+
+  if (offset !== undefined) {
+    queryParams["o"] = offset;
+  }
+
+  if (count !== undefined) {
+    queryParams["c"] = count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserRecentlyPlayedGames.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetUserRecentlyPlayedGamesResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "GameID",
+      "ConsoleID",
+      "NumPossibleAchievements",
+      "PossibleScore",
+      "NumAchieved",
+      "ScoreAchieved",
+      "NumAchievedHardcore",
+      "ScoreAchievedHardcore"
+    ]
+  });
+};

package/src/user/getUserSummary.test.ts

@@ -0,0 +1,251 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserSummary } from "./getUserSummary";
+import type { GetUserSummaryResponse, UserSummary } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserSummary", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserSummary).toBeDefined();
+  });
+
+  it("given a username, retrieves user summary information about the user", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse = mockGetUserSummaryResponse;
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserSummary.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserSummary(authorization, {
+      userName: "WCopeland"
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockExpectedSummaryValue);
+  });
+});
+
+const mockGetUserSummaryResponse: GetUserSummaryResponse = {
+  RecentlyPlayedCount: 2,
+  RecentlyPlayed: [
+    {
+      GameID: "19020",
+      ConsoleID: "21",
+      ConsoleName: "PlayStation 2",
+      Title: "Mortal Kombat: Deadly Alliance",
+      ImageIcon: "/Images/064938.png",
+      LastPlayed: "2023-01-27 02:05:02"
+    },
+    {
+      GameID: "15922",
+      ConsoleID: "7",
+      ConsoleName: "NES",
+      Title: "~Hack~ Mega Man 3 Revamped",
+      ImageIcon: "/Images/061792.png",
+      LastPlayed: "2022-11-07 21:49:09"
+    }
+  ],
+  MemberSince: "2020-02-02 20:10:35",
+  LastActivity: {
+    ID: "59195489",
+    timestamp: "2023-01-27 02:13:21",
+    lastupdate: "2023-01-27 02:13:21",
+    activitytype: "1",
+    User: "WCopeland",
+    data: "281263",
+    data2: "1"
+  },
+  RichPresenceMsg: "Arcade [Match 2] - Nitara vs Drahmin (Novice difficulty)",
+  LastGameID: "19020",
+  LastGame: {
+    ID: 19_020,
+    Title: "Mortal Kombat: Deadly Alliance",
+    ConsoleID: 21,
+    ForumTopicID: 19_339,
+    Flags: 0,
+    ImageIcon: "/Images/064938.png",
+    ImageTitle: "/Images/057355.png",
+    ImageIngame: "/Images/057356.png",
+    ImageBoxArt: "/Images/056153.png",
+    Publisher: "Midway",
+    Developer: "Midway",
+    Genre: "3D Fighting",
+    Released: "November 16, 2002",
+    IsFinal: false,
+    ConsoleName: "PlayStation 2",
+    RichPresencePatch: "MockRichPresencePatch"
+  },
+  ContribCount: "0",
+  ContribYield: "0",
+  TotalPoints: "18817",
+  TotalSoftcorePoints: "25",
+  TotalTruePoints: "56984",
+  Permissions: "1",
+  Untracked: "0",
+  ID: "117089",
+  UserWallActive: "1",
+  Motto: "https://i.imgur.com/ov30jeD.jpg",
+  Rank: 1372,
+  Awarded: {
+    "1829": {
+      NumPossibleAchievements: "80",
+      PossibleScore: "738",
+      NumAchieved: "16",
+      ScoreAchieved: "95",
+      NumAchievedHardcore: "16",
+      ScoreAchievedHardcore: "95"
+    },
+    "6278": {
+      NumPossibleAchievements: "42",
+      PossibleScore: "478",
+      NumAchieved: 0,
+      ScoreAchieved: 0,
+      NumAchievedHardcore: 0,
+      ScoreAchievedHardcore: 0
+    }
+  },
+  RecentAchievements: {
+    "19020": {
+      "281248": {
+        ID: "281248",
+        GameID: "19020",
+        GameTitle: "Mortal Kombat: Deadly Alliance",
+        Title: "Head Stomp",
+        Description: "Perform a Fatality as Jax.",
+        Points: "3",
+        BadgeName: "311063",
+        IsAwarded: "1",
+        DateAwarded: "2023-01-27 02:04:36",
+        HardcoreAchieved: "0"
+      }
+    }
+  },
+  Points: "18817",
+  SoftcorePoints: "25",
+  UserPic: "/UserPic/WCopeland.png",
+  TotalRanked: 34_572,
+  Status: "Offline"
+};
+
+const mockExpectedSummaryValue: UserSummary = {
+  recentlyPlayedCount: 2,
+  recentlyPlayed: [
+    {
+      gameId: 19_020,
+      consoleId: 21,
+      consoleName: "PlayStation 2",
+      title: "Mortal Kombat: Deadly Alliance",
+      imageIcon: "/Images/064938.png",
+      lastPlayed: "2023-01-27 02:05:02"
+    },
+    {
+      gameId: 15_922,
+      consoleId: 7,
+      consoleName: "NES",
+      title: "~Hack~ Mega Man 3 Revamped",
+      imageIcon: "/Images/061792.png",
+      lastPlayed: "2022-11-07 21:49:09"
+    }
+  ],
+  memberSince: "2020-02-02 20:10:35",
+  lastActivity: {
+    id: 59_195_489,
+    timestamp: "2023-01-27 02:13:21",
+    lastupdate: "2023-01-27 02:13:21",
+    activitytype: 1,
+    user: "WCopeland",
+    data: "281263",
+    data2: "1"
+  },
+  richPresenceMsg: "Arcade [Match 2] - Nitara vs Drahmin (Novice difficulty)",
+  lastGameId: 19_020,
+  lastGame: {
+    id: 19_020,
+    title: "Mortal Kombat: Deadly Alliance",
+    consoleId: 21,
+    forumTopicId: 19_339,
+    flags: 0,
+    imageIcon: "/Images/064938.png",
+    imageTitle: "/Images/057355.png",
+    imageIngame: "/Images/057356.png",
+    imageBoxArt: "/Images/056153.png",
+    publisher: "Midway",
+    developer: "Midway",
+    genre: "3D Fighting",
+    released: "November 16, 2002",
+    isFinal: false,
+    consoleName: "PlayStation 2",
+    richPresencePatch: "MockRichPresencePatch"
+  },
+  contribCount: 0,
+  contribYield: 0,
+  totalPoints: 18_817,
+  totalSoftcorePoints: 25,
+  totalTruePoints: 56_984,
+  permissions: 1,
+  untracked: false,
+  id: 117_089,
+  userWallActive: true,
+  motto: "https://i.imgur.com/ov30jeD.jpg",
+  rank: 1372,
+  awarded: {
+    "1829": {
+      numPossibleAchievements: 80,
+      possibleScore: 738,
+      numAchieved: 16,
+      scoreAchieved: 95,
+      numAchievedHardcore: 16,
+      scoreAchievedHardcore: 95
+    },
+    "6278": {
+      numPossibleAchievements: 42,
+      possibleScore: 478,
+      numAchieved: 0,
+      scoreAchieved: 0,
+      numAchievedHardcore: 0,
+      scoreAchievedHardcore: 0
+    }
+  },
+  recentAchievements: {
+    19_020: {
+      281_248: {
+        id: 281_248,
+        gameId: 19_020,
+        gameTitle: "Mortal Kombat: Deadly Alliance",
+        title: "Head Stomp",
+        description: "Perform a Fatality as Jax.",
+        points: 3,
+        badgeName: "311063",
+        isAwarded: true,
+        dateAwarded: "2023-01-27 02:04:36",
+        hardcoreAchieved: false
+      }
+    }
+  },
+  points: 18_817,
+  softcorePoints: 25,
+  userPic: "/UserPic/WCopeland.png",
+  totalRanked: 34_572,
+  status: "Offline"
+};

package/src/user/getUserSummary.ts

@@ -0,0 +1,96 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @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.
+ *
+ * @param payload.recentAchievementsCount Optional. The number of recent achievements
+ * to return. This defaults to 5.
+ *
+ * @example
+ * ```
+ * const userSummary = await getUserSummary(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing summary metadata about a target user.
+ */
+export const getUserSummary = async (
+  authorization: AuthObject,
+  payload: {
+    userName: string;
+    recentGamesCount?: number;
+    recentAchievementsCount?: number;
+  }
+): Promise<UserSummary> => {
+  const { userName, recentGamesCount, recentAchievementsCount } = payload;
+
+  const queryParams: Record<string, string | number> = { u: userName };
+
+  if (recentGamesCount !== undefined) {
+    queryParams["g"] = recentGamesCount;
+  }
+
+  if (recentAchievementsCount !== undefined) {
+    queryParams["a"] = recentAchievementsCount;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserSummary.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetUserSummaryResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "GameID",
+      "ConsoleID",
+      "ID",
+      "LastGameID",
+      "ForumTopicID",
+      "activitytype",
+      "ContribCount",
+      "ContribYield",
+      "TotalPoints",
+      "TotalSoftcorePoints",
+      "TotalTruePoints",
+      "Permissions",
+      "NumPossibleAchievements",
+      "PossibleScore",
+      "NumAchieved",
+      "ScoreAchieved",
+      "NumAchievedHardcore",
+      "ScoreAchievedHardcore",
+      "Points",
+      "SoftcorePoints"
+    ],
+    shouldMapToBooleans: [
+      "Untracked",
+      "UserWallActive",
+      "IsAwarded",
+      "HardcoreAchieved"
+    ]
+  });
+};
+
+// TODO: add test for this

package/src/user/index.ts

@@ -0,0 +1,9 @@
+export * from "./getAchievementsEarnedBetween";
+export * from "./getAchievementsEarnedOnDay";
+export * from "./getGameInfoAndUserProgress";
+export * from "./getUserGameRankAndScore";
+export * from "./getUserPoints";
+export * from "./getUserProgress";
+export * from "./getUserRecentlyPlayedGames";
+export * from "./getUserSummary";
+export * from "./models";

package/src/user/models/dated-user-achievement.model.ts

@@ -0,0 +1,17 @@
+export type DatedUserAchievement = {
+  date: string;
+  hardcoreMode: boolean;
+  achievementId: number;
+  title: string;
+  description: string;
+  badgeName: string;
+  points: number;
+  author: string;
+  gameTitle: string;
+  gameIcon: string;
+  gameId: number;
+  consoleName: string;
+  cumulScore: number;
+  badgeUrl: string;
+  gameUrl: string;
+}[];