@retroachievements/api 0.0.0-development

package/src/game/getGameRankAndScore.test.ts

@@ -0,0 +1,62 @@
+/* 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 { getGameRankAndScore } from "./getGameRankAndScore";
+import type { GetGameRankAndScoreResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGameRankAndScore", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGameRankAndScore).toBeDefined();
+  });
+
+  it("given a game ID, retrieves metadata about latest masteries for a game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameRankAndScoreResponse = [
+      {
+        User: "Arekdias",
+        TotalScore: "189",
+        LastAward: "2020-10-10 22:43:32",
+        Rank: 1
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetGameRankAndScore.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGameRankAndScore(authorization, {
+      gameId: 14_402,
+      type: "high-scores"
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        user: "Arekdias",
+        totalScore: 189,
+        lastAward: "2020-10-10 22:43:32",
+        rank: 1
+      }
+    ]);
+  });
+});

package/src/game/getGameRankAndScore.ts

@@ -0,0 +1,66 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GameRankAndScoreEntity,
+  GetGameRankAndScoreResponse
+} from "./models";
+
+/**
+ * A call to this function will retrieve metadata about
+ * either the latest masters for a game, or the highest
+ * points earners for a game. The game is 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".
+ *
+ * @param payload.type Can either be "latest-masters" or "high-scores".
+ *
+ * @example
+ * ```
+ * const gameRankAndScore = await getGameRankAndScore(
+ *   authorization,
+ *   { gameId: 14402, type: "latest-masters" }
+ * );
+ * ```
+ *
+ * @returns An array containing a list of latest masters or
+ * high score earners for a given game ID.
+ * ```json
+ * [
+ *   {  user: 'Arekdias', totalScore: 189, lastAward: '2020-10-10 22:43:32' }
+ * ]
+ * ```
+ */
+export const getGameRankAndScore = async (
+  authorization: AuthObject,
+  payload: { gameId: number; type: "latest-masters" | "high-scores" }
+): Promise<GameRankAndScoreEntity[]> => {
+  const { gameId, type } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameRankAndScore.php",
+    authorization,
+    {
+      g: gameId,
+      t: type === "latest-masters" ? 1 : 0
+    }
+  );
+
+  const rawResponse = await call<GetGameRankAndScoreResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["TotalScore"]
+  });
+};

package/src/game/getGameRating.test.ts

@@ -0,0 +1,59 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getGameRating } from "./getGameRating";
+import type { GetGameRatingResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getGameRating", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getGameRating).toBeDefined();
+  });
+
+  it("given a game ID, retrieves metadata about how users have rated it", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetGameRatingResponse = {
+      GameID: 14_402,
+      Ratings: {
+        Game: 3.1875,
+        Achievements: 0,
+        GameNumVotes: 16,
+        AchievementsNumVotes: 0
+      }
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetGameRating.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getGameRating(authorization, { gameId: 14_402 });
+
+    // ASSERT
+    expect(response).toEqual({
+      gameId: 14_402,
+      ratings: {
+        game: 3.1875,
+        achievements: 0,
+        gameNumVotes: 16,
+        achievementsNumVotes: 0
+      }
+    });
+  });
+});

package/src/game/getGameRating.ts

@@ -0,0 +1,59 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GameRating, GetGameRatingResponse } from "./models";
+
+/**
+ * A call to this function will retrieve metadata about
+ * how users have rated the game and its set.
+ *
+ * @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 gameRating = await getGameRating(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object with game rating metadata.
+ * ```json
+ * {
+ *   gameId: 14402,
+ *   ratings: {
+ *     game: 3.1875,
+ *     achievements: 0,
+ *     gameNumVotes: 16,
+ *     achievementsNumVotes: 0
+ *   }
+ * }
+ * ```
+ */
+export const getGameRating = async (
+  authorization: AuthObject,
+  payload: { gameId: number }
+): Promise<GameRating> => {
+  const { gameId } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameRating.php",
+    authorization,
+    { i: gameId }
+  );
+
+  const rawResponse = await call<GetGameRatingResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/game/index.ts

@@ -0,0 +1,7 @@
+export * from "./getAchievementCount";
+export * from "./getAchievementDistribution";
+export * from "./getGame";
+export * from "./getGameExtended";
+export * from "./getGameRankAndScore";
+export * from "./getGameRating";
+export * from "./models";

package/src/game/models/achievement-count.model.ts

@@ -0,0 +1,4 @@
+export interface AchievementCount {
+  gameId: number;
+  achievementIds: number[];
+}

package/src/game/models/achievement-distribution-flags.model.ts

@@ -0,0 +1,4 @@
+export enum AchievementDistributionFlags {
+  CoreAchievements = 3,
+  UnofficialAchievements = 5
+}

package/src/game/models/game-extended-achievement-entity.model.ts

@@ -0,0 +1,15 @@
+export interface GameExtendedAchievementEntity {
+  id: number;
+  numAwarded: number;
+  numAwardedHardcore: number;
+  title: string;
+  description: string;
+  points: number;
+  trueRatio: number;
+  author: string;
+  dateModified: string;
+  dateCreated: string;
+  badgeName: string;
+  displayOrder: number;
+  memAddr: string;
+}

package/src/game/models/game-extended-claim-entity.model.ts

@@ -0,0 +1,7 @@
+export interface GameExtendedClaimEntity {
+  user: string;
+  setType: number;
+  claimType: number;
+  created: string;
+  expiration: string;
+}

package/src/game/models/game-extended.model.ts

@@ -0,0 +1,26 @@
+import type { GameExtendedAchievementEntity } from "./game-extended-achievement-entity.model";
+import type { GameExtendedClaimEntity } from "./game-extended-claim-entity.model";
+
+export interface GameExtended {
+  id: number;
+  title: string;
+  consoleId: number;
+  forumTopicId: number;
+  flags: number;
+  imageIcon: string;
+  imageTitle: string;
+  imageIngame: string;
+  imageBoxArt: string;
+  publisher: string;
+  developer: string;
+  genre: string;
+  released: number;
+  isFinal: boolean;
+  consoleName: string;
+  richPresencePatch: string;
+  numAchievements: number;
+  numDistinctPlayersCasual: number;
+  numDistinctPlayersHardcore: number;
+  claims: GameExtendedClaimEntity[];
+  achievements: Record<number, GameExtendedAchievementEntity>;
+}

package/src/game/models/game-rank-and-score-entity.model.ts

@@ -0,0 +1,6 @@
+export interface GameRankAndScoreEntity {
+  user: string;
+  totalScore: number;
+  lastAward: string;
+  rank: number;
+}

package/src/game/models/game-rating.model.ts

@@ -0,0 +1,9 @@
+export interface GameRating {
+  gameId: number;
+  ratings: {
+    game: number;
+    achievements: number;
+    gameNumVotes: number;
+    achievementsNumVotes: number;
+  };
+}

package/src/game/models/game.model.ts

@@ -0,0 +1,19 @@
+export interface Game {
+  id: number;
+  title: string;
+  forumTopicId: number;
+  consoleId: number;
+  consoleName: string;
+  flags: number;
+  imageIcon: string;
+  gameIcon: string;
+  imageTitle: string;
+  imageIngame: string;
+  imageBoxArt: string;
+  publisher: string;
+  developer: string;
+  genre: string;
+  released: number;
+  gameTitle: string;
+  console: string;
+}

package/src/game/models/get-achievement-count-response.model.ts

@@ -0,0 +1,4 @@
+export interface GetAchievementCountResponse {
+  GameID: number;
+  AchievementIDs: number[];
+}

package/src/game/models/get-achievement-distribution-response.model.ts

@@ -0,0 +1 @@
+export type GetAchievementDistributionResponse = Record<`${number}`, number>;

package/src/game/models/get-game-extended-response.model.ts

@@ -0,0 +1,56 @@
+// NOTE: This cannot be a true extension of the `GetGameResponse`
+// interface because the return types for many of these fields
+// are different from the actual RA API.
+
+enum GameExtendedClaimType {
+  Primary = "0",
+  Collaboration = "1"
+}
+
+export interface GameExtendedRawAchievementEntity {
+  ID: string;
+  NumAwarded: string;
+  NumAwardedHardcore: string;
+  Title: string;
+  Description: string;
+  Points: string;
+  TrueRatio: string;
+  Author: string;
+  DateModified: string;
+  DateCreated: string;
+  BadgeName: string;
+  DisplayOrder: string;
+  MemAddr: string;
+}
+
+interface GameExtendedRawClaimEntity {
+  User: string;
+  SetType: string;
+  ClaimType: GameExtendedClaimType;
+  Created: string;
+  Expiration: string;
+}
+
+export interface GetGameExtendedResponse {
+  ID: number;
+  Title: string;
+  ConsoleID: number;
+  ForumTopicID: number;
+  Flags: number;
+  ImageIcon: string;
+  ImageTitle: string;
+  ImageIngame: string;
+  ImageBoxArt: string;
+  Publisher: string;
+  Developer: string;
+  Genre: string;
+  Released: string;
+  IsFinal: boolean;
+  ConsoleName: string;
+  RichPresencePatch: string;
+  NumAchievements: number;
+  NumDistinctPlayersCasual: string;
+  NumDistinctPlayersHardcore: string;
+  Claims: GameExtendedRawClaimEntity[];
+  Achievements: Record<number, GameExtendedRawAchievementEntity> | [];
+}

package/src/game/models/get-game-rank-and-score-response.model.ts

@@ -0,0 +1,8 @@
+interface RawGameRankAndScoreEntity {
+  User: string;
+  TotalScore: string;
+  LastAward: string;
+  Rank: number;
+}
+
+export type GetGameRankAndScoreResponse = RawGameRankAndScoreEntity[];

package/src/game/models/get-game-rating-response.model.ts

@@ -0,0 +1,9 @@
+export interface GetGameRatingResponse {
+  GameID: number;
+  Ratings: {
+    Game: number;
+    Achievements: number;
+    GameNumVotes: number;
+    AchievementsNumVotes: number;
+  };
+}

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

@@ -0,0 +1,19 @@
+export interface GetGameResponse {
+  ID: string;
+  Title: string;
+  ForumTopicID: string;
+  ConsoleID: string;
+  ConsoleName: string;
+  Flags: string;
+  ImageIcon: string;
+  GameIcon: string;
+  ImageTitle: string;
+  ImageIngame: string;
+  ImageBoxArt: string;
+  Publisher: string;
+  Developer: string;
+  Genre: string;
+  Released: string;
+  GameTitle: string;
+  Console: string;
+}

package/src/game/models/index.ts

@@ -0,0 +1,14 @@
+export * from "./achievement-count.model";
+export * from "./achievement-distribution-flags.model";
+export * from "./game.model";
+export * from "./game-extended.model";
+export * from "./game-extended-achievement-entity.model";
+export * from "./game-extended-claim-entity.model";
+export * from "./game-rank-and-score-entity.model";
+export * from "./game-rating.model";
+export * from "./get-achievement-count-response.model";
+export * from "./get-achievement-distribution-response.model";
+export * from "./get-game-extended-response.model";
+export * from "./get-game-rank-and-score-response.model";
+export * from "./get-game-rating-response.model";
+export * from "./get-game-response.model";

package/src/index.ts

@@ -0,0 +1,8 @@
+// This file is the single public-facing API of the entire library.
+
+export * from "./achievement";
+export * from "./console";
+export * from "./feed";
+export * from "./game";
+export * from "./user";
+export * from "./utils/public";

package/src/user/getAchievementsEarnedBetween.test.ts

@@ -0,0 +1,84 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getAchievementsEarnedBetween } from "./getAchievementsEarnedBetween";
+import type { DatedUserAchievementsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementsEarnedBetween", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementsEarnedBetween).toBeDefined();
+  });
+
+  it("retrieves a list of user achievements earned between a set of dates", 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_GetAchievementsEarnedBetween.php`,
+        (_, res, ctx) => res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getAchievementsEarnedBetween(authorization, {
+      userName: "xelnia",
+      fromDate: new Date("2022-10-12"),
+      toDate: new Date("2022-10-13")
+    });
+
+    // 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/getAchievementsEarnedBetween.ts

@@ -0,0 +1,88 @@
+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 between two provided dates.
+ *
+ * @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.toDate A Date object specifying when
+ * the list itself should end.
+ *
+ * @example
+ * ```
+ * const achievementsEarnedBetween = await getAchievementsEarnedBetween(
+ *   authorization,
+ *   {
+ *     userName: "xelnia",
+ *     fromDate: new Date("2022-10-12"),
+ *     toDate: new Date("2022-10-13")
+ *   }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user
+ * achievements earned during the specified date range.
+ * ```
+ *  [
+ *    {
+ *      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 getAchievementsEarnedBetween = async (
+  authorization: AuthObject,
+  payload: { userName: string; fromDate: Date; toDate: Date }
+): Promise<DatedUserAchievement[]> => {
+  const { userName, fromDate, toDate } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementsEarnedBetween.php",
+    authorization,
+    {
+      u: userName,
+      f: (fromDate.getTime() / 1000).toFixed(0),
+      t: (toDate.getTime() / 1000).toFixed(0)
+    }
+  );
+
+  const rawResponse = await call<DatedUserAchievementsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["AchievementID", "Points", "GameID"],
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};