@retroachievements/api 0.0.0-development

package/src/game/getAchievementDistribution.test.ts

@@ -0,0 +1,187 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getAchievementDistribution } from "./getAchievementDistribution";
+import {
+  type GetAchievementDistributionResponse,
+  AchievementDistributionFlags
+} from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementDistribution", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementDistribution).toBeDefined();
+  });
+
+  it("given a game ID, retrieves the achievement distribution associated with the game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementDistributionResponse = {
+      "1": 20,
+      "2": 10,
+      "3": 8,
+      "4": 4,
+      "5": 1
+    };
+
+    let detectedSearchParams: URLSearchParams;
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementDistribution.php`,
+        (req, res, ctx) => {
+          detectedSearchParams = req.url.searchParams;
+          return res(ctx.json(mockResponse));
+        }
+      )
+    );
+
+    // ACT
+    const response = await getAchievementDistribution(authorization, {
+      gameId: 14_402
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+
+    expect(detectedSearchParams!.get("i")).toEqual("14402");
+    expect(detectedSearchParams!.has("f")).toBeFalsy();
+    expect(detectedSearchParams!.has("h")).toBeFalsy();
+  });
+
+  it("given flags, successfully attaches the option to the call", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementDistributionResponse = {
+      "1": 20,
+      "2": 10,
+      "3": 8,
+      "4": 4,
+      "5": 1
+    };
+
+    let detectedSearchParams: URLSearchParams;
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementDistribution.php`,
+        (req, res, ctx) => {
+          detectedSearchParams = req.url.searchParams;
+          return res(ctx.json(mockResponse));
+        }
+      )
+    );
+
+    // ACT
+    const response = await getAchievementDistribution(authorization, {
+      gameId: 14_402,
+      flags: AchievementDistributionFlags.UnofficialAchievements
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+
+    expect(detectedSearchParams!.get("i")).toEqual("14402");
+    expect(detectedSearchParams!.get("f")).toEqual(
+      String(AchievementDistributionFlags.UnofficialAchievements)
+    );
+    expect(detectedSearchParams!.has("h")).toBeFalsy();
+  });
+
+  it("given a truthy hardcore value, successfully attaches the option to the call", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementDistributionResponse = {
+      "1": 20,
+      "2": 10,
+      "3": 8,
+      "4": 4,
+      "5": 1
+    };
+
+    let detectedSearchParams: URLSearchParams;
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementDistribution.php`,
+        (req, res, ctx) => {
+          detectedSearchParams = req.url.searchParams;
+          return res(ctx.json(mockResponse));
+        }
+      )
+    );
+
+    // ACT
+    const response = await getAchievementDistribution(authorization, {
+      gameId: 14_402,
+      hardcore: true
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+
+    expect(detectedSearchParams!.get("i")).toEqual("14402");
+    expect(detectedSearchParams!.get("h")).toEqual("1");
+  });
+
+  it("given a falsy hardcore value, successfully attaches the option to the call", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementDistributionResponse = {
+      "1": 20,
+      "2": 10,
+      "3": 8,
+      "4": 4,
+      "5": 1
+    };
+
+    let detectedSearchParams: URLSearchParams;
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementDistribution.php`,
+        (req, res, ctx) => {
+          detectedSearchParams = req.url.searchParams;
+          return res(ctx.json(mockResponse));
+        }
+      )
+    );
+
+    // ACT
+    const response = await getAchievementDistribution(authorization, {
+      gameId: 14_402,
+      hardcore: false
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+
+    expect(detectedSearchParams!.get("i")).toEqual("14402");
+    expect(detectedSearchParams!.get("h")).toEqual("0");
+  });
+});

package/src/game/getAchievementDistribution.ts

@@ -0,0 +1,88 @@
+import { apiBaseUrl, buildRequestUrl, call } from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  AchievementDistributionFlags,
+  GetAchievementDistributionResponse
+} from "./models";
+
+/**
+ * A call to this function will retrieve a dictionary
+ * of the number of players who have earned a specific
+ * number of achievements for a given 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.flags Optional. By default, only official achievement
+ * tallies are returned in the response. Import the `AchievementDistributionFlags`
+ * enum for possible values. This lets you see the count of players who have
+ * unlocked unofficial achievements.
+ *
+ * @param payload.hardcore Optional. By default, set to false, with both
+ * softcore and hardcore tallies returned in the response. If this option
+ * is set to true, only hardcore unlocks will be included in the totals.
+ *
+ * @example
+ * ```
+ * const achievementDistribution = await getAchievementDistribution(
+ *   authorization,
+ *   { gameId: 14402, hardcore: true }
+ * );
+ * ```
+ *
+ * @returns A dictionary where the keys represent the earned achievement
+ * count and the values represent the number of players who have unlocked
+ * that many achievements.
+ * ```
+ * {
+ *   '1': 64,
+ *   '2': 19,
+ *   '3': 11,
+ *   '4': 18,
+ *   '5': 25,
+ *   '6': 20,
+ *   '7': 26,
+ *   '8': 29,
+ *   '9': 54,
+ *   '10': 17,
+ *   '11': 29,
+ *   '12': 4
+ * }
+ * ```
+ */
+export const getAchievementDistribution = async (
+  authorization: AuthObject,
+  payload: {
+    gameId: number;
+    flags?: AchievementDistributionFlags;
+    hardcore?: boolean;
+  }
+) => {
+  const { gameId, flags, hardcore } = payload;
+
+  const queryParams: Record<string, any> = { i: gameId };
+
+  if (flags !== undefined) {
+    queryParams["f"] = flags;
+  }
+
+  if (hardcore !== undefined) {
+    queryParams["h"] = hardcore === true ? 1 : 0;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementDistribution.php",
+    authorization,
+    queryParams
+  );
+
+  return await call<GetAchievementDistributionResponse>({
+    url
+  });
+};

package/src/game/getGame.test.ts

@@ -0,0 +1,81 @@
+/* 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 { getGame } from "./getGame";
+import type { GetGameResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGame", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGame).toBeDefined();
+  });
+
+  it("given a game ID, retrieves basic metadata about the game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameResponse = {
+      ID: "14402",
+      Title: "Dragster",
+      ForumTopicID: "9145",
+      ConsoleID: "25",
+      ConsoleName: "Atari 2600",
+      Flags: "0",
+      ImageIcon: "/Images/026368.png",
+      GameIcon: "/Images/026368.png",
+      ImageTitle: "/Images/026366.png",
+      ImageIngame: "/Images/026367.png",
+      ImageBoxArt: "/Images/026365.png",
+      Publisher: "Activision ",
+      Developer: "David Crane",
+      Genre: "Racing",
+      Released: "1980",
+      GameTitle: "Dragster",
+      Console: "Atari 2600"
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetGame.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGame(authorization, { gameId: 14_402 });
+
+    // ASSERT
+    expect(response).toEqual({
+      id: 14_402,
+      title: "Dragster",
+      forumTopicId: 9145,
+      consoleId: 25,
+      consoleName: "Atari 2600",
+      flags: 0,
+      imageIcon: "/Images/026368.png",
+      gameIcon: "/Images/026368.png",
+      imageTitle: "/Images/026366.png",
+      imageIngame: "/Images/026367.png",
+      imageBoxArt: "/Images/026365.png",
+      publisher: "Activision ",
+      developer: "David Crane",
+      genre: "Racing",
+      released: 1980,
+      gameTitle: "Dragster",
+      console: "Atari 2600"
+    });
+  });
+});

package/src/game/getGame.ts

@@ -0,0 +1,74 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { Game, GetGameResponse } from "./models";
+
+/**
+ * A call to this function will retrieve basic metadata about
+ * a game, targeted via its unique 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".
+ *
+ * @example
+ * ```
+ * const game = await getGame(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object containing basic metadata about a target game.
+ * ```json
+ * {
+ *   id: 14402,
+ *   title: "Dragster",
+ *   forumTopicId: 9145,
+ *   consoleId: 25,
+ *   consoleName: "Atari 2600",
+ *   flags: 0,
+ *   imageIcon: "/Images/026368.png",
+ *   gameIcon: "/Images/026368.png",
+ *   imageTitle: "/Images/026366.png",
+ *   imageIngame: "/Images/026367.png",
+ *   imageBoxArt: "/Images/026365.png",
+ *   publisher: "Activision",
+ *   developer: "David Crane",
+ *   genre: "Racing",
+ *   released: 1980,
+ *   gameTitle: "Dragster",
+ *   console: "Atari 2600"
+ * }
+ * ```
+ */
+export const getGame = async (
+  authorization: AuthObject,
+  payload: { gameId: number }
+): Promise<Game> => {
+  const { gameId } = payload;
+
+  const url = buildRequestUrl(apiBaseUrl, "/API_GetGame.php", authorization, {
+    i: gameId
+  });
+
+  const rawResponse = await call<GetGameResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "ID",
+      "ForumTopicID",
+      "ConsoleID",
+      "Flags",
+      "Released"
+    ]
+  });
+};

package/src/game/getGameExtended.test.ts

@@ -0,0 +1,121 @@
+/* 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 { getGameExtended } from "./getGameExtended";
+import type { GetGameExtendedResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGameExtended", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGameExtended).toBeDefined();
+  });
+
+  it("given a game ID, retrieves extended metadata about the game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameExtendedResponse = {
+      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",
+      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"
+        }
+      }
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetGameExtended.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGameExtended(authorization, { gameId: 14_402 });
+
+    // 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,
+      claims: [],
+      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"
+        }
+      }
+    });
+  });
+});

package/src/game/getGameExtended.ts

@@ -0,0 +1,103 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GameExtended, GetGameExtendedResponse } from "./models";
+
+/**
+ * A call to this function will retrieve extended metadata
+ * about a game, targeted via its unique 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".
+ *
+ * @example
+ * ```
+ * const gameExtended = await getGameExtended(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object containing extended metadata about a target game.
+ * ```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"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export const getGameExtended = async (
+  authorization: AuthObject,
+  payload: { gameId: number }
+): Promise<GameExtended> => {
+  const { gameId } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameExtended.php",
+    authorization,
+    {
+      i: gameId
+    }
+  );
+
+  const rawResponse = await call<GetGameExtendedResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "ID",
+      "NumAwarded",
+      "NumAwardedHardcore",
+      "Points",
+      "TrueRatio",
+      "DisplayOrder",
+      "NumDistinctPlayersCasual",
+      "NumDistinctPlayersHardcore",
+      "Released"
+    ]
+  });
+};