@retroachievements/api 0.0.0-development

package/src/user/getAchievementsEarnedOnDay.test.ts

@@ -0,0 +1,83 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getAchievementsEarnedOnDay } from "./getAchievementsEarnedOnDay";
+import type { DatedUserAchievementsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementsEarnedOnDay", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementsEarnedOnDay).toBeDefined();
+  });
+
+  it("retrieves a list of user achievements earned on a specified date", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: DatedUserAchievementsResponse = [
+      {
+        Date: "2022-10-12 07:36:31",
+        HardcoreMode: "1",
+        AchievementID: "173356",
+        Title: "Wind Beneath My Wings",
+        Description: "Collect all objects in the Wings Category.",
+        BadgeName: "193797",
+        Points: "10",
+        Author: "blendedsea",
+        GameTitle: "Me & My Katamari",
+        GameIcon: "/Images/047357.png",
+        GameID: "3571",
+        ConsoleName: "PlayStation Portable",
+        CumulScore: 40,
+        BadgeURL: "/Badge/193797.png",
+        GameURL: "/game/3571"
+      }
+    ];
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementsEarnedOnDay.php`,
+        (_, res, ctx) => res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getAchievementsEarnedOnDay(authorization, {
+      userName: "xelnia",
+      onDate: new Date("2022-10-12")
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        date: "2022-10-12 07:36:31",
+        hardcoreMode: true,
+        achievementId: 173_356,
+        title: "Wind Beneath My Wings",
+        description: "Collect all objects in the Wings Category.",
+        badgeName: "193797",
+        points: 10,
+        author: "blendedsea",
+        gameTitle: "Me & My Katamari",
+        gameIcon: "/Images/047357.png",
+        gameId: 3571,
+        consoleName: "PlayStation Portable",
+        cumulScore: 40,
+        badgeUrl: "/Badge/193797.png",
+        gameUrl: "/game/3571"
+      }
+    ]);
+  });
+});

package/src/user/getAchievementsEarnedOnDay.ts

@@ -0,0 +1,87 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  DatedUserAchievement,
+  DatedUserAchievementsResponse
+} from "./models";
+
+/**
+ * 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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.userName The user for which to retrieve the
+ * list of achievements for.
+ *
+ * @param payload.fromDate A Date object specifying when
+ * the list itself should begin.
+ *
+ * @param payload.onDate A Date object specifying the day
+ * to query for a user's earned achievements.
+ *
+ * @example
+ * ```
+ * const achievementsEarnedOnDay = await getAchievementsEarnedOnDay(
+ *   authorization,
+ *   {
+ *     userName: "xelnia",
+ *     onDate: new Date("2022-10-13")
+ *   }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user
+ * achievements earned on the specified day.
+ * ```
+ *  [
+ *    {
+ *      date: '2022-10-12 07:58:05',
+ *      hardcoreMode: true,
+ *      achievementId: 173315,
+ *      title: 'Your Puny Human Weapons',
+ *      description: 'Collect all objects in the Weapons Category.',
+ *      badgeName: '193756',
+ *      points: 10,
+ *      author: 'blendedsea',
+ *      gameTitle: 'Me & My Katamari',
+ *      gameIcon: '/Images/047357.png',
+ *      gameId: 3571,
+ *      consoleName: 'PlayStation Portable',
+ *      cumulScore: 120,
+ *      badgeUrl: '/Badge/193756.png',
+ *      gameUrl: '/game/3571'
+ *    }
+ *  ]
+ * ```
+ */
+export const getAchievementsEarnedOnDay = async (
+  authorization: AuthObject,
+  payload: { userName: string; onDate: Date }
+): Promise<DatedUserAchievement[]> => {
+  const { userName, onDate } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementsEarnedOnDay.php",
+    authorization,
+    {
+      u: userName,
+      // YYYY-MM-DD
+      d: `${onDate.getFullYear()}-${onDate.getMonth() + 1}-${onDate.getDate()}`
+    }
+  );
+
+  const rawResponse = await call<DatedUserAchievementsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["AchievementID", "Points", "GameID"],
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};

package/src/user/getGameInfoAndUserProgress.test.ts

@@ -0,0 +1,135 @@
+/* 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 { getGameInfoAndUserProgress } from "./getGameInfoAndUserProgress";
+import type { GetGameInfoAndUserProgressResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGameInfoAndUserProgress", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGameInfoAndUserProgress).toBeDefined();
+  });
+
+  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",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameInfoAndUserProgressResponse = {
+      ID: 14_402,
+      Title: "Dragster",
+      ConsoleID: 25,
+      ForumTopicID: 9145,
+      Flags: 0,
+      ImageIcon: "/Images/026368.png",
+      ImageTitle: "/Images/026366.png",
+      ImageIngame: "/Images/026367.png",
+      ImageBoxArt: "/Images/026365.png",
+      Publisher: "Activision ",
+      Developer: "David Crane",
+      Genre: "Racing",
+      Released: "1980",
+      IsFinal: false,
+      ConsoleName: "Atari 2600",
+      RichPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
+      NumAchievements: 12,
+      NumDistinctPlayersCasual: "454",
+      NumDistinctPlayersHardcore: "323",
+      Achievements: {
+        "79434": {
+          ID: "79434",
+          NumAwarded: "338",
+          NumAwardedHardcore: "253",
+          Title: "Novice Dragster Driver 1",
+          Description: "Complete your very first race in game 1.",
+          Points: "1",
+          TrueRatio: "1",
+          Author: "Boldewin",
+          DateModified: "2019-08-01 19:03:46",
+          DateCreated: "2019-07-31 18:49:57",
+          BadgeName: "85541",
+          DisplayOrder: "0",
+          MemAddr: "f5c41fa0b5fa0d5fbb8a74c598f18582",
+          DateEarned: "2022-08-23 22:56:38",
+          DateEarnedHardcore: "2022-08-23 22:56:38"
+        }
+      },
+      NumAwardedToUser: 12,
+      NumAwardedToUserHardcore: 12,
+      UserCompletion: "100.00%",
+      UserCompletionHardcore: "100.00%"
+    };
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetGameInfoAndUserProgress.php`,
+        (_, res, ctx) => res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGameInfoAndUserProgress(authorization, {
+      gameId: 14_402,
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      id: 14_402,
+      title: "Dragster",
+      consoleId: 25,
+      forumTopicId: 9145,
+      flags: 0,
+      imageIcon: "/Images/026368.png",
+      imageTitle: "/Images/026366.png",
+      imageIngame: "/Images/026367.png",
+      imageBoxArt: "/Images/026365.png",
+      publisher: "Activision ",
+      developer: "David Crane",
+      genre: "Racing",
+      released: 1980,
+      isFinal: false,
+      consoleName: "Atari 2600",
+      richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
+      numAchievements: 12,
+      numDistinctPlayersCasual: 454,
+      numDistinctPlayersHardcore: 323,
+      achievements: {
+        "79434": {
+          id: 79_434,
+          numAwarded: 338,
+          numAwardedHardcore: 253,
+          title: "Novice Dragster Driver 1",
+          description: "Complete your very first race in game 1.",
+          points: 1,
+          trueRatio: 1,
+          author: "Boldewin",
+          dateModified: "2019-08-01 19:03:46",
+          dateCreated: "2019-07-31 18:49:57",
+          badgeName: "85541",
+          displayOrder: 0,
+          memAddr: "f5c41fa0b5fa0d5fbb8a74c598f18582",
+          dateEarned: "2022-08-23 22:56:38",
+          dateEarnedHardcore: "2022-08-23 22:56:38"
+        }
+      },
+      numAwardedToUser: 12,
+      numAwardedToUserHardcore: 12,
+      userCompletion: "100.00%",
+      userCompletionHardcore: "100.00%"
+    });
+  });
+});

package/src/user/getGameInfoAndUserProgress.ts

@@ -0,0 +1,118 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GameInfoAndUserProgress,
+  GetGameInfoAndUserProgressResponse
+} from "./models";
+
+/**
+ * A call to this function will retrieve extended metadata
+ * 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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.gameId The unique game ID. If you are unsure, open the
+ * game's page on the RetroAchievements.org website. For example, Dragster's
+ * 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
+ * game progress for.
+ *
+ * @example
+ * ```
+ * const gameInfoAndUserProgress = await getGameInfoAndUserProgress(
+ *   authorization,
+ *   { gameId: 14402, userName: "wv_pinball" }
+ * );
+ * ```
+ *
+ * @returns An object containing extended metadata about a target game,
+ * with attached progress for a target username.
+ * ```json
+ * {
+ *   id: 14402,
+ *   title: "Dragster",
+ *   consoleId: 25,
+ *   forumTopicId: 9145,
+ *   flags: 0,
+ *   imageIcon: "/Images/026368.png",
+ *   imageTitle: "/Images/026366.png",
+ *   imageIngame: "/Images/026367.png",
+ *   imageBoxArt: "/Images/026365.png",
+ *   publisher: "Activision",
+ *   developer: "David Crane",
+ *   genre: "Racing",
+ *   released: 1980,
+ *   isFinal: false,
+ *   consoleName: "Atari 2600",
+ *   richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
+ *   numAchievements: 12,
+ *   numDistinctPlayersCasual: 454,
+ *   numDistinctPlayersHardcore, 323
+ *   claims: [],
+ *   achievements: {
+ *     '79434': {
+ *       id: 79434,
+ *       numAwarded: 338,
+ *       numAwardedHardcore: 253,
+ *       title: "Novice Dragster Driver 1",
+ *       description: "Complete your very first race in game 1.",
+ *       points: 1,
+ *       trueRatio: 1,
+ *       author: "Boldewin",
+ *       dateModified: "2019-08-01 19:03:46",
+ *       dateCreated: "2019-07-31 18:49:57",
+ *       badgeName: "85541",
+ *       displayOrder: 0,
+ *       memAddr: "f5c41fa0b5fa0d5fbb8a74c598f18582",
+ *       dateEarned: '2022-08-23 22:56:38',
+ *       dateEarnedHardcore: '2022-08-23 22:56:38'
+ *     }
+ *   },
+ *   numAwardedToUser: 12,
+ *   numAwardedToUserHardcore: 12,
+ *   userCompletion: "100.00%",
+ *   userCompletionHardcore: "100.00%"
+ * }
+ * ```
+ */
+export const getGameInfoAndUserProgress = async (
+  authorization: AuthObject,
+  payload: { gameId: number; userName: string }
+): Promise<GameInfoAndUserProgress> => {
+  const { gameId, userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameInfoAndUserProgress.php",
+    authorization,
+    {
+      g: gameId,
+      u: userName
+    }
+  );
+
+  const rawResponse = await call<GetGameInfoAndUserProgressResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "ID",
+      "NumAwarded",
+      "NumAwardedHardcore",
+      "Points",
+      "TrueRatio",
+      "DisplayOrder",
+      "NumDistinctPlayersCasual",
+      "NumDistinctPlayersHardcore",
+      "Released"
+    ]
+  });
+};

package/src/user/getUserGameRankAndScore.test.ts

@@ -0,0 +1,60 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserGameRankAndScore } from "./getUserGameRankAndScore";
+import type { GetUserGameRankAndScoreResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserGameRankAndScore", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserGameRankAndScore).toBeDefined();
+  });
+
+  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",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserGameRankAndScoreResponse = [
+      {
+        User: "xelnia",
+        TotalScore: "1000",
+        LastAward: "2022-09-01 21:51:23",
+        UserRank: "4"
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserGameRankAndScore.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserGameRankAndScore(authorization, {
+      userName: "xelnia",
+      gameId: 14_402
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        user: "xelnia",
+        totalScore: 1000,
+        lastAward: "2022-09-01 21:51:23",
+        userRank: 4
+      }
+    ]);
+  });
+});

package/src/user/getUserGameRankAndScore.ts

@@ -0,0 +1,69 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserGameRankAndScoreResponse,
+  UserGameRankAndScore
+} from "./models";
+
+/**
+ * A call to this function will retrieve metadata about
+ * how a particular user has performed/ranked on a particular
+ * game, targeted by game ID.
+ *
+ * @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
+ * game's page on the RetroAchievements.org website. For example, Dragster's
+ * 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
+ * game ranking metadata for.
+ *
+ * @example
+ * ```
+ * const userGameRankAndScore = await getUserGameRankAndScore(
+ *   authorization,
+ *   { gameId: 14402, userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user's
+ * rank and score for the target game ID. If metadata
+ * cannot be found, the array is empty.
+ * ```
+ * [
+ *   {
+ *     user: "xelnia",
+ *     totalScore: 378,
+ *     lastAward: "2022-09-01 21:51:23",
+ *     userRank: 3
+ *   }
+ * ]
+ * ```
+ */
+export const getUserGameRankAndScore = async (
+  authorization: AuthObject,
+  payload: { gameId: number; userName: string }
+): Promise<UserGameRankAndScore> => {
+  const { gameId, userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserGameRankAndScore.php",
+    authorization,
+    { g: gameId, u: userName }
+  );
+
+  const rawResponse = await call<GetUserGameRankAndScoreResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["TotalScore", "UserRank"]
+  });
+};

package/src/user/getUserPoints.test.ts

@@ -0,0 +1,49 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserPoints } from "./getUserPoints";
+import type { GetUserPointsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserPoints", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserPoints).toBeDefined();
+  });
+
+  it("given a username, retrieves the point values associated with the user", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserPointsResponse = {
+      Points: 10_000,
+      SoftcorePoints: 5400
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserPoints.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserPoints(authorization, { userName: "xelnia" });
+
+    // ASSERT
+    expect(response).toEqual({
+      points: 10_000,
+      softcorePoints: 5400
+    });
+  });
+});

package/src/user/getUserPoints.ts

@@ -0,0 +1,51 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+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.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.userName The user for which to retrieve the points for.
+ *
+ * @example
+ * ```
+ * const userPoints = await getUserPoints(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing metadata about a target user's points.
+ * ```json
+ * {
+ *   points: 7640,
+ *   softcorePoints: 25
+ * }
+ * ```
+ */
+export const getUserPoints = async (
+  authorization: AuthObject,
+  payload: { userName: string }
+): Promise<UserPoints> => {
+  const { userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserPoints.php",
+    authorization,
+    { u: userName }
+  );
+
+  const rawResponse = await call<GetUserPointsResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};