@retroachievements/api 0.0.0-development

package/src/achievement/models/achievement-unlock-entity.model.ts

@@ -0,0 +1,6 @@
+export interface AchievementUnlockEntity {
+  user: string;
+  raPoints: number;
+  dateAwarded: string;
+  hardcoreMode: boolean;
+}

package/src/achievement/models/get-achievement-unlocks-response.model.ts

@@ -0,0 +1,8 @@
+interface AchievementUnlocksResponseEntity {
+  User: string;
+  RAPoints: string;
+  DateAwarded: string;
+  HardcoreMode: string;
+}
+
+export type GetAchievementUnlocksResponse = AchievementUnlocksResponseEntity[];

package/src/achievement/models/index.ts

@@ -0,0 +1,2 @@
+export * from "./achievement-unlock-entity.model";
+export * from "./get-achievement-unlocks-response.model";

package/src/console/getConsoleIds.test.ts

@@ -0,0 +1,53 @@
+/* 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 { getConsoleIds } from "./getConsoleIds";
+import type { GetConsoleIdsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getConsoleIds", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getConsoleIds).toBeDefined();
+  });
+
+  it("retrieves a list of console IDs and their names and cleans properties", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetConsoleIdsResponse = [
+      { ID: "1", Name: "Mega Drive" },
+      { ID: "2", Name: "Nintendo 64" },
+      { ID: "3", Name: "SNES" }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetConsoleIDs.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getConsoleIds(authorization);
+
+    // ASSERT
+    expect(response).toEqual([
+      { id: 1, name: "Mega Drive" },
+      { id: 2, name: "Nintendo 64" },
+      { id: 3, name: "SNES" }
+    ]);
+  });
+});

package/src/console/getConsoleIds.ts

@@ -0,0 +1,43 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { ConsoleId, GetConsoleIdsResponse } from "./models";
+
+/**
+ * A call to this function will retrieve the complete list
+ * of console ID and name pairs on the RetroAchievements.org
+ * platform.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @example
+ * ```
+ * const consoleIds = await getConsoleIds(authorization);
+ * ```
+ *
+ * @returns An array containing a complete list of console ID
+ * and name pairs for RetroAchievements.org.
+ * ```
+ * { id: "1", name: "Mega Drive" }
+ * ```
+ */
+export const getConsoleIds = async (
+  authorization: AuthObject
+): Promise<ConsoleId[]> => {
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetConsoleIDs.php",
+    authorization
+  );
+
+  const rawResponse = await call<GetConsoleIdsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["ID"]
+  });
+};

package/src/console/getGameList.test.ts

@@ -0,0 +1,82 @@
+/* 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 { getGameList } from "./getGameList";
+import type { GetGameListResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGameList", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGameList).toBeDefined();
+  });
+
+  it("retrieves a list of games and cleans their properties", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameListResponse = [
+      {
+        Title: "Elemental Master",
+        ID: "4247",
+        ConsoleID: "1",
+        ConsoleName: "Mega Drive",
+        ImageIcon: "/Images/048245.png",
+        NumAchievements: 44,
+        NumLeaderboards: 0,
+        Points: 500,
+        DateModified: "2021-12-09 17:05:39",
+        ForumTopicID: 1972,
+        Hashes: [
+          "32e1a15161ef1f070b023738353bde51",
+          "9b04970a603ace521c7cca2acaf69804"
+        ]
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetGameList.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGameList(authorization, {
+      consoleId: 1,
+      shouldRetrieveGameHashes: true
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        title: "Elemental Master",
+        id: 4247,
+        consoleId: 1,
+        consoleName: "Mega Drive",
+        imageIcon: "/Images/048245.png",
+        numAchievements: 44,
+        numLeaderboards: 0,
+        points: 500,
+        dateModified: "2021-12-09 17:05:39",
+        forumTopicId: 1972,
+        hashes: [
+          "32e1a15161ef1f070b023738353bde51",
+          "9b04970a603ace521c7cca2acaf69804"
+        ]
+      }
+    ]);
+  });
+});

package/src/console/getGameList.ts

@@ -0,0 +1,94 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GameList, GetGameListResponse } from "./models";
+
+/**
+ * A call to this function will retrieve the complete list
+ * of games for a specified console on the RetroAchievements.org
+ * platform.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.consoleId The unique console ID to retrieve a list of
+ * games from. The list of consoleIds can be retrieved using the `getConsoleIds()`
+ * function provided by this library.
+ *
+ * @param payload.shouldOnlyRetrieveGamesWithAchievements If truthy, will not
+ * return games that do not have achievements.
+ *
+ * @param payload.shouldRetrieveGameHashes If truthy, will return valid
+ * hashes for game ROMs in an array attached to each game in the list.
+ *
+ * @example
+ * ```
+ * const gameList = await getGameList(
+ *   authorization,
+ *   { consoleId: 1, shouldOnlyRetrieveGamesWithAchievements: true }
+ * );
+ * ```
+ *
+ * @returns An array containing a list of games for a given consoleId.
+ * ```
+ * [
+ *   {
+ *     title: "Elemental Master",
+ *     id: 4247,
+ *     consoleId: 1,
+ *     consoleName: "Mega Drive",
+ *     imageIcon: "/Images/048245.png",
+ *     numAchievements: 44,
+ *     numLeaderboards: 0,
+ *     points: 500,
+ *     dateModified: "2021-12-09 17:05:39",
+ *     forumTopicId: 1972,
+ *     hashes: ["32e1a15161ef1f070b023738353bde51"]
+ *   }
+ * ]
+ * ```
+ */
+export const getGameList = async (
+  authorization: AuthObject,
+  payload: {
+    consoleId: number;
+    shouldOnlyRetrieveGamesWithAchievements?: boolean;
+    shouldRetrieveGameHashes?: boolean;
+  }
+): Promise<GameList> => {
+  const {
+    consoleId,
+    shouldOnlyRetrieveGamesWithAchievements,
+    shouldRetrieveGameHashes
+  } = payload;
+
+  let callPayload: Record<string, any> = { i: consoleId };
+
+  if (shouldOnlyRetrieveGamesWithAchievements !== undefined) {
+    callPayload = {
+      ...callPayload,
+      f: shouldOnlyRetrieveGamesWithAchievements ? 1 : 0
+    };
+  }
+
+  if (shouldRetrieveGameHashes) {
+    callPayload = { ...callPayload, h: shouldRetrieveGameHashes ? 1 : 0 };
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameList.php",
+    authorization,
+    callPayload
+  );
+
+  const rawResponse = await call<GetGameListResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["ID", "ConsoleID"]
+  });
+};

package/src/console/index.ts

@@ -0,0 +1,3 @@
+export * from "./getConsoleIds";
+export * from "./getGameList";
+export * from "./models";

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

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

package/src/console/models/game-list.model.ts

@@ -0,0 +1,16 @@
+interface GameEntity {
+  title: string;
+  id: number;
+  consoleId: number;
+  consoleName: string;
+  imageIcon: string;
+  numAchievements: number;
+  numLeaderboards: number;
+  points: number;
+  dateModified: string;
+  forumTopicId: number;
+
+  hashes?: string[];
+}
+
+export type GameList = GameEntity[];

package/src/console/models/get-console-ids-response.model.ts

@@ -0,0 +1 @@
+export type GetConsoleIdsResponse = readonly { ID: string; Name: string }[];

package/src/console/models/get-game-list-response.model.ts

@@ -0,0 +1,16 @@
+interface RawGameListEntity {
+  Title: string;
+  ID: string;
+  ConsoleID: string;
+  ConsoleName: string;
+  ImageIcon: string;
+  NumAchievements: number;
+  NumLeaderboards: number;
+  Points: number;
+  DateModified: string;
+  ForumTopicID: number;
+
+  Hashes?: string[];
+}
+
+export type GetGameListResponse = RawGameListEntity[];

package/src/console/models/index.ts

@@ -0,0 +1,4 @@
+export * from "./console-id.model";
+export * from "./game-list.model";
+export * from "./get-console-ids-response.model";
+export * from "./get-game-list-response.model";

package/src/feed/getAchievementOfTheWeek.test.ts

@@ -0,0 +1,167 @@
+/* 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 { getAchievementOfTheWeek } from "./getAchievementOfTheWeek";
+import type { GetAchievementOfTheWeekResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementOfTheWeek", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementOfTheWeek).toBeDefined();
+  });
+
+  it("retrieves metadata about the current achievement of the week and cleans properties", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementOfTheWeekResponse = {
+      Achievement: {
+        ID: "165062",
+        Title: "The True Hero",
+        Description: "Receive any Ending as Han [Normal or Hard]",
+        Points: "10",
+        TrueRatio: "22",
+        Author: "BigWeedSmokerMan",
+        DateCreated: "2021-08-08 17:47:46",
+        DateModified: "2021-08-09 12:20:05"
+      },
+      Console: { ID: "39", Title: "Saturn" },
+      ForumTopic: { ID: "14767" },
+      Game: { ID: "14513", Title: "Guardian Heroes" },
+      StartAt: "2022-10-10 00:00:00",
+      TotalPlayers: "219",
+      Unlocks: [
+        {
+          User: "Tirbaba2",
+          RAPoints: "72",
+          DateAwarded: "2022-10-10 01:42:19",
+          HardcoreMode: "1"
+        }
+      ],
+      UnlocksCount: "40"
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetAchievementOfTheWeek.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getAchievementOfTheWeek(authorization);
+
+    // ASSERT
+    expect(response).toEqual({
+      achievement: {
+        id: 165_062,
+        title: "The True Hero",
+        description: "Receive any Ending as Han [Normal or Hard]",
+        points: 10,
+        trueRatio: 22,
+        author: "BigWeedSmokerMan",
+        dateCreated: "2021-08-08 17:47:46",
+        dateModified: "2021-08-09 12:20:05"
+      },
+      console: { id: 39, title: "Saturn" },
+      forumTopic: { id: 14_767 },
+      game: { id: 14_513, title: "Guardian Heroes" },
+      startAt: "2022-10-10 00:00:00",
+      totalPlayers: 219,
+      unlocks: [
+        {
+          user: "Tirbaba2",
+          raPoints: 72,
+          dateAwarded: "2022-10-10 01:42:19",
+          hardcoreMode: true
+        }
+      ],
+      unlocksCount: 40
+    });
+  });
+
+  it("properly sets the hardcore boolean value when cleaning properties", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementOfTheWeekResponse = {
+      Achievement: {
+        ID: "165062",
+        Title: "The True Hero",
+        Description: "Receive any Ending as Han [Normal or Hard]",
+        Points: "10",
+        TrueRatio: "22",
+        Author: "BigWeedSmokerMan",
+        DateCreated: "2021-08-08 17:47:46",
+        DateModified: "2021-08-09 12:20:05"
+      },
+      Console: { ID: "39", Title: "Saturn" },
+      ForumTopic: { ID: "14767" },
+      Game: { ID: "14513", Title: "Guardian Heroes" },
+      StartAt: "2022-10-10 00:00:00",
+      TotalPlayers: "219",
+      Unlocks: [
+        {
+          User: "Tirbaba2",
+          RAPoints: "72",
+          DateAwarded: "2022-10-10 01:42:19",
+          HardcoreMode: "0"
+        }
+      ],
+      UnlocksCount: "40"
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetAchievementOfTheWeek.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getAchievementOfTheWeek(authorization);
+
+    // ASSERT
+    expect(response).toEqual({
+      achievement: {
+        id: 165_062,
+        title: "The True Hero",
+        description: "Receive any Ending as Han [Normal or Hard]",
+        points: 10,
+        trueRatio: 22,
+        author: "BigWeedSmokerMan",
+        dateCreated: "2021-08-08 17:47:46",
+        dateModified: "2021-08-09 12:20:05"
+      },
+      console: { id: 39, title: "Saturn" },
+      forumTopic: { id: 14_767 },
+      game: { id: 14_513, title: "Guardian Heroes" },
+      startAt: "2022-10-10 00:00:00",
+      totalPlayers: 219,
+      unlocks: [
+        {
+          user: "Tirbaba2",
+          raPoints: 72,
+          dateAwarded: "2022-10-10 01:42:19",
+          hardcoreMode: false
+        }
+      ],
+      unlocksCount: 40
+    });
+  });
+});

package/src/feed/getAchievementOfTheWeek.ts

@@ -0,0 +1,80 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  AchievementOfTheWeek,
+  GetAchievementOfTheWeekResponse
+} from "./models";
+
+/**
+ * A call to this function will retrieve comprehensive
+ * metadata about the current Achievement of the Week.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @example
+ * ```
+ * const achievementOfTheWeek = await getAchievementOfTheWeek(
+ *   authorization
+ * );
+ * ```
+ *
+ * @returns An object containing comprehensive metadata
+ * about the current Achievement of the Week.
+ * ```
+ * {
+ *   achievement: {
+ *     id: "165062",
+ *     title: "The True Hero",
+ *     description: "Receive any Ending as Han [Normal or Hard]",
+ *     points: "10",
+ *     trueRatio: "22",
+ *     author: "BigWeedSmokerMan",
+ *     dateCreated: "2021-08-08 17:47:46",
+ *     dateModified: "2021-08-09 12:20:05"
+ *   },
+ *   console: { id: "39", title: "Saturn" },
+ *   forumTopic: { id: "14767" },
+ *   game: { id: "14513", title: "Guardian Heroes" },
+ *   startAt: "2022-10-10 00:00:00",
+ *   totalPlayers: "219",
+ *   unlocks: [
+ *     {
+ *       user: "Tirbaba2",
+ *       rAPoints: "72",
+ *       dateAwarded: "2022-10-10 01:42:19",
+ *       hardcoreMode: "1"
+ *     }
+ *   ],
+ *   unlocksCount: "40"
+ * }
+ * ```
+ */
+export const getAchievementOfTheWeek = async (
+  authorization: AuthObject
+): Promise<AchievementOfTheWeek> => {
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementOfTheWeek.php",
+    authorization
+  );
+
+  const rawResponse = await call<GetAchievementOfTheWeekResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "ID",
+      "Points",
+      "TrueRatio",
+      "TotalPlayers",
+      "RAPoints",
+      "UnlocksCount"
+    ],
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};

package/src/feed/getActiveClaims.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 { getActiveClaims } from "./getActiveClaims";
+import type { GetActiveClaimsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getActiveClaims", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getActiveClaims).toBeDefined();
+  });
+
+  it("retrieves metadata about current active claims", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetActiveClaimsResponse = [
+      {
+        ID: "7043",
+        User: "siouxerskate",
+        GameID: "3726",
+        GameTitle: "Tactics Ogre: Let Us Cling Together",
+        GameIcon: "/Images/049640.png",
+        ConsoleName: "PlayStation Portable",
+        ClaimType: "0",
+        SetType: "0",
+        Status: "0",
+        Extension: "0",
+        Special: "0",
+        Created: "2022-10-03 20:29:45",
+        DoneTime: "2023-01-03 20:29:45",
+        Updated: "2022-10-03 20:29:45",
+        MinutesLeft: "112285"
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetActiveClaims.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getActiveClaims(authorization);
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        id: 7043,
+        user: "siouxerskate",
+        gameId: 3726,
+        gameTitle: "Tactics Ogre: Let Us Cling Together",
+        gameIcon: "/Images/049640.png",
+        consoleName: "PlayStation Portable",
+        claimType: 0,
+        setType: 0,
+        status: 0,
+        extension: 0,
+        special: 0,
+        created: "2022-10-03 20:29:45",
+        doneTime: "2023-01-03 20:29:45",
+        updated: "2022-10-03 20:29:45",
+        minutesLeft: 112_285
+      }
+    ]);
+  });
+});