@retroachievements/api 0.0.0-development

package/src/user/models/dated-user-achievements-response.model.ts

@@ -0,0 +1,20 @@
+interface DatedUserAchievementResponseEntity {
+  Date: string;
+  HardcoreMode: string;
+  AchievementID: string;
+  Title: string;
+  Description: string;
+  BadgeName: string;
+  Points: string;
+  Author: string;
+  GameTitle: string;
+  GameIcon: string;
+  GameID: string;
+  ConsoleName: string;
+  CumulScore: number;
+  BadgeURL: string;
+  GameURL: string;
+}
+
+export type DatedUserAchievementsResponse =
+  DatedUserAchievementResponseEntity[];

package/src/user/models/game-info-and-user-progress.model.ts

@@ -0,0 +1,19 @@
+import type {
+  GameExtended,
+  GameExtendedAchievementEntity
+} from "../../game/models";
+
+export type GameExtendedAchievementEntityWithUserProgress =
+  GameExtendedAchievementEntity & {
+    dateEarned: string;
+    dateEarnedHardcore: string;
+  };
+
+export interface GameInfoAndUserProgress extends GameExtended {
+  achievements: Record<number, GameExtendedAchievementEntityWithUserProgress>;
+
+  numAwardedToUser: number;
+  numAwardedToUserHardcore: number;
+  userCompletion: string;
+  userCompletionHardcore: string;
+}

package/src/user/models/get-game-info-and-user-progress-response.model.ts

@@ -0,0 +1,28 @@
+import type {
+  GameExtendedRawAchievementEntity,
+  GetGameExtendedResponse
+} from "../../game/models";
+
+type GetGameExtendedResponseWithoutClaims = Omit<
+  GetGameExtendedResponse,
+  "Claims"
+>;
+
+type GameExtendedRawAchievementEntityWithUserProgress =
+  GameExtendedRawAchievementEntity & {
+    DateEarned: string;
+    DateEarnedHardcore: string;
+  };
+
+export interface GetGameInfoAndUserProgressResponse
+  extends GetGameExtendedResponseWithoutClaims {
+  Achievements: Record<
+    number,
+    GameExtendedRawAchievementEntityWithUserProgress
+  >;
+
+  NumAwardedToUser: number;
+  NumAwardedToUserHardcore: number;
+  UserCompletion: string;
+  UserCompletionHardcore: string;
+}

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

@@ -0,0 +1,9 @@
+interface UserGameRankAndScoreResponseEntity {
+  User: string;
+  TotalScore: string;
+  LastAward: string;
+  UserRank: string;
+}
+
+export type GetUserGameRankAndScoreResponse =
+  UserGameRankAndScoreResponseEntity[];

package/src/user/models/get-user-points-response.model.ts

@@ -0,0 +1,4 @@
+export interface GetUserPointsResponse {
+  Points: number;
+  SoftcorePoints: number;
+}

package/src/user/models/get-user-progress-response.model.ts

@@ -0,0 +1,13 @@
+interface UserProgressResponseEntity {
+  NumPossibleAchievements: string;
+  PossibleScore: string;
+  NumAchieved: number | string;
+  ScoreAchieved: number | string;
+  NumAchievedHardcore: number | string;
+  ScoreAchievedHardcore: number | string;
+}
+
+export type GetUserProgressResponse = Record<
+  `${number}`,
+  UserProgressResponseEntity
+>;

package/src/user/models/get-user-recently-played-games-response.model.ts

@@ -0,0 +1,17 @@
+interface UserRecentlyPlayedGameResponseEntity {
+  GameID: string;
+  ConsoleID: string;
+  ConsoleName: string;
+  Title: string;
+  ImageIcon: string;
+  LastPlayed: string;
+  NumPossibleAchievements: string;
+  PossibleScore: string;
+  NumAchieved: string | number;
+  ScoreAchieved: string | number;
+  NumAchievedHardcore: string | number;
+  ScoreAchievedHardcore: string | number;
+}
+
+export type GetUserRecentlyPlayedGamesResponse =
+  UserRecentlyPlayedGameResponseEntity[];

package/src/user/models/get-user-summary-response.model.ts

@@ -0,0 +1,92 @@
+interface RecentlyPlayedGameEntity {
+  GameID: string;
+  ConsoleID: string;
+  ConsoleName: string;
+  Title: string;
+  ImageIcon: string;
+  LastPlayed: string;
+}
+
+interface RecentlyAwardedAchievementEntity {
+  NumPossibleAchievements: string;
+  PossibleScore: string;
+  NumAchieved: number | string;
+  ScoreAchieved: number | string;
+  NumAchievedHardcore: number | string;
+  ScoreAchievedHardcore: number | string;
+}
+
+interface ExtendedRecentAchievementEntity {
+  ID: string;
+  GameID: string;
+  GameTitle: string;
+  Title: string;
+  Description: string;
+  Points: string;
+  BadgeName: string;
+  IsAwarded: "1";
+  DateAwarded: string;
+  HardcoreAchieved: "0";
+}
+
+interface LastGameEntity {
+  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;
+}
+
+export interface GetUserSummaryResponse {
+  RecentlyPlayedCount: number;
+  RecentlyPlayed: RecentlyPlayedGameEntity[];
+  MemberSince: string;
+
+  LastActivity: {
+    ID: string;
+    timestamp: string;
+    lastupdate: string;
+    activitytype: string;
+    User: string;
+    data: string;
+    data2: string;
+  };
+
+  RichPresenceMsg: string;
+  LastGameID: string;
+  LastGame: LastGameEntity;
+  ContribCount: string;
+  ContribYield: string;
+  TotalPoints: string;
+  TotalSoftcorePoints: string;
+  TotalTruePoints: string;
+  Permissions: string;
+  Untracked: "0" | "1";
+  ID: string;
+  UserWallActive: "0" | "1";
+  Motto: string;
+  Rank: number;
+  Awarded: Record<`${number}`, RecentlyAwardedAchievementEntity>;
+
+  RecentAchievements: Record<
+    `${number}`,
+    Record<`${number}`, ExtendedRecentAchievementEntity>
+  >;
+
+  Points: string;
+  SoftcorePoints: string;
+  UserPic: string;
+  TotalRanked: number;
+  Status: string;
+}

package/src/user/models/index.ts

@@ -0,0 +1,14 @@
+export * from "./dated-user-achievement.model";
+export * from "./dated-user-achievements-response.model";
+export * from "./game-info-and-user-progress.model";
+export * from "./get-game-info-and-user-progress-response.model";
+export * from "./get-user-game-rank-and-score-response.model";
+export * from "./get-user-points-response.model";
+export * from "./get-user-progress-response.model";
+export * from "./get-user-recently-played-games-response.model";
+export * from "./get-user-summary-response.model";
+export * from "./user-game-rank-and-score.model";
+export * from "./user-points.model";
+export * from "./user-progress.model";
+export * from "./user-recently-played-games.model";
+export * from "./user-summary.model";

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

@@ -0,0 +1,8 @@
+interface UserGameRankAndScoreEntity {
+  user: string;
+  totalScore: number;
+  lastAward: string;
+  userRank: number;
+}
+
+export type UserGameRankAndScore = UserGameRankAndScoreEntity[];

package/src/user/models/user-points.model.ts

@@ -0,0 +1,4 @@
+export interface UserPoints {
+  points: number;
+  softcorePoints: number;
+}

package/src/user/models/user-progress.model.ts

@@ -0,0 +1,10 @@
+interface UserProgressEntity {
+  numPossibleAchievements: number;
+  possibleScore: number;
+  numAchieved: number;
+  scoreAchieved: number;
+  numAchievedHardcore: number;
+  scoreAchievedHardcore: number;
+}
+
+export type UserProgress = Record<`${number}`, UserProgressEntity>;

package/src/user/models/user-recently-played-games.model.ts

@@ -0,0 +1,16 @@
+interface UserRecentlyPlayedGameEntity {
+  gameId: number;
+  consoleId: number;
+  consoleName: string;
+  title: string;
+  imageIcon: string;
+  lastPlayed: string;
+  numPossibleAchievements: number;
+  possibleScore: number;
+  numAchieved: number;
+  scoreAchieved: number;
+  numAchievedHardcore: number;
+  scoreAchievedHardcore: number;
+}
+
+export type UserRecentlyPlayedGames = UserRecentlyPlayedGameEntity[];

package/src/user/models/user-summary.model.ts

@@ -0,0 +1,92 @@
+interface RecentlyPlayedGameEntity {
+  gameId: number;
+  consoleId: number;
+  consoleName: string;
+  title: string;
+  imageIcon: string;
+  lastPlayed: string;
+}
+
+interface LastActivityEntity {
+  id: number;
+  timestamp: string;
+  lastupdate: string;
+  activitytype: number;
+  user: string;
+  data: string;
+  data2: string;
+}
+
+interface LastGameEntity {
+  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;
+}
+
+interface AwardedGameEntity {
+  numPossibleAchievements: number;
+  possibleScore: number;
+  numAchieved: number;
+  scoreAchieved: number;
+  numAchievedHardcore: number;
+  scoreAchievedHardcore: number;
+}
+
+interface ExtendedRecentAchievementEntity {
+  id: number;
+  gameId: number;
+  gameTitle: string;
+  title: string;
+  description: string;
+  points: number;
+  badgeName: string;
+  isAwarded: true;
+  dateAwarded: string;
+  hardcoreAchieved: false;
+}
+
+export interface UserSummary {
+  recentlyPlayedCount: number;
+  recentlyPlayed: RecentlyPlayedGameEntity[];
+  memberSince: string;
+  lastActivity: LastActivityEntity;
+  richPresenceMsg: string;
+  lastGameId: number;
+  lastGame: LastGameEntity;
+  contribCount: number;
+  contribYield: number;
+  totalPoints: number;
+  totalSoftcorePoints: number;
+  totalTruePoints: number;
+  permissions: number;
+  untracked: boolean;
+  id: number;
+  userWallActive: boolean;
+  motto: string;
+  rank: number;
+  awarded: Record<`${number}`, AwardedGameEntity>;
+
+  recentAchievements: Record<
+    `${number}`,
+    Record<`${number}`, ExtendedRecentAchievementEntity>
+  >;
+
+  points: number;
+  softcorePoints: number;
+  userPic: string;
+  totalRanked: number;
+  status: string;
+}

package/src/utils/internal/apiBaseUrl.ts

@@ -0,0 +1 @@
+export const apiBaseUrl = "https://retroachievements.org/API";

package/src/utils/internal/buildRequestUrl.test.ts

@@ -0,0 +1,51 @@
+import { buildRequestUrl } from "./buildRequestUrl";
+
+describe("Util: buildRequestUrl", () => {
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(buildRequestUrl).toBeDefined();
+  });
+
+  it("given a baseUrl, endpointUrl, and some arguments, returns a correctly-constructed URL", () => {
+    // ARRANGE
+    const baseUrl = "https://retroachievements.org/API/";
+    const endpointUrl = "/:baz/API_GetConsoleIDs.php";
+
+    const args = {
+      baz: "myBazValue",
+      limit: 10,
+      offset: 2,
+      notDefined: undefined
+    };
+
+    // ACT
+    const requestUrl = buildRequestUrl(
+      baseUrl,
+      endpointUrl,
+      { userName: "TestUser", webApiKey: "mockWebApiKey" },
+      args as any
+    );
+
+    // ASSERT
+    expect(requestUrl).toEqual(
+      "https://retroachievements.org/API/myBazValue/API_GetConsoleIDs.php?z=TestUser&y=mockWebApiKey&limit=10&offset=2"
+    );
+  });
+
+  it("given no arguments, returns a correctly-constructed URL", () => {
+    // ARRANGE
+    const baseUrl = "https://retroachievements.org/API/";
+    const endpointUrl = "/:baz/API_GetConsoleIDs.php";
+
+    // ACT
+    const requestUrl = buildRequestUrl(baseUrl, endpointUrl, {
+      userName: "TestUser",
+      webApiKey: "mockWebApiKey"
+    });
+
+    // ASSERT
+    expect(requestUrl).toEqual(
+      "https://retroachievements.org/API/:baz/API_GetConsoleIDs.php?z=TestUser&y=mockWebApiKey"
+    );
+  });
+});

package/src/utils/internal/buildRequestUrl.ts

@@ -0,0 +1,32 @@
+import type { AuthObject } from "../public/models";
+
+export const buildRequestUrl = (
+  baseUrl: string,
+  endpointUrl: string,
+  authObject: AuthObject,
+  args: Record<string, string | number> = {}
+) => {
+  const concatenated = `${baseUrl}/${endpointUrl}`;
+  const withoutDoubleSlashes = concatenated.replace(/([^:]\/)\/+/g, "$1");
+
+  let withArgs = withoutDoubleSlashes;
+
+  // `z` and `y` are expected query params from the RA API.
+  // Authentication is handled purely by query params.
+  const queryParamValues: Record<string, string> = {
+    z: authObject.userName,
+    y: authObject.webApiKey
+  };
+
+  for (const [argKey, argValue] of Object.entries(args)) {
+    // "abc.com/some-route/:foo/some-path" & {"foo": 4} --> "abc.com/some-route/4/some-path"
+    if (withArgs.includes(`:${argKey}`)) {
+      withArgs = withArgs.replace(`:${argKey}`, String(argValue));
+    } else if (argValue !== undefined) {
+      queryParamValues[argKey] = String(argValue);
+    }
+  }
+
+  const queryString = new URLSearchParams(queryParamValues).toString();
+  return `${withArgs}?${queryString}`;
+};

package/src/utils/internal/call.test.ts

@@ -0,0 +1,39 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { call } from "./call";
+
+const server = setupServer();
+
+describe("Util: call", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(call).toBeDefined();
+  });
+
+  it("given a url, makes a GET call", async () => {
+    // ARRANGE
+    let receivedMethod = "";
+
+    const mockRequestUrl = "https://abc.xyz/v1/endpoint";
+
+    server.use(
+      rest.get(mockRequestUrl, (req, res, ctx) => {
+        receivedMethod = req.method;
+        return res(ctx.json({ foo: "bar" }));
+      })
+    );
+
+    // ACT
+    const response = await call({ url: mockRequestUrl });
+
+    // ASSERT
+    expect(response).toEqual({ foo: "bar" });
+    expect(receivedMethod).toEqual("GET");
+  });
+});

package/src/utils/internal/call.ts

@@ -0,0 +1,29 @@
+import unfetch from "isomorphic-unfetch";
+
+/**
+ * Fetch an HTTP resource. This is publicly exposed in the
+ * event you would like to access an endpoint that this
+ * library does not currently support.
+ *
+ * UNLESS YOU'RE SURE OF WHAT YOU'RE DOING, YOU PROBABLY
+ * SHOULDN'T USE THIS FUNCTION.
+ *
+ * 2022-10-09: At the time of writing, Node.js LTS (16.x)
+ * does not yet support fetch. As a result, we pull in
+ * isomorphic-unfetch for Node.js compatibility. Our support
+ * matrix includes 14.x and 16.x.
+ *
+ * @FIXME - When Node.js 20.x is released, remove the
+ * isomorphic-unfetch dependency. At that point we will have
+ * two major LTS versions that include a native fetch API.
+ */
+export const call = async <
+  T extends readonly any[] | Record<string, any>
+>(config: {
+  url: string;
+}) => {
+  const { url } = config;
+
+  const rawResponse = await unfetch(url);
+  return (await rawResponse.json()) as T;
+};

package/src/utils/internal/index.ts

@@ -0,0 +1,4 @@
+export * from "./apiBaseUrl";
+export * from "./buildRequestUrl";
+export * from "./call";
+export * from "./serializeProperties";

package/src/utils/internal/serializeProperties.test.ts

@@ -0,0 +1,141 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { serializeProperties } from "./serializeProperties";
+
+describe("Util: serializeProperties", () => {
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(serializeProperties).toBeDefined();
+  });
+
+  it("can serialize a simple object", () => {
+    // ARRANGE
+    const originalObject = {
+      ID: 1,
+      GameID: 100,
+      AchievementIDs: [1, 2, 3, 4, 5],
+      RAPoints: 100,
+      ConsoleName: "PlayStation Portable"
+    };
+
+    // ACT
+    const sanitizedObject = serializeProperties(originalObject);
+
+    // ASSERT
+    expect(sanitizedObject).toEqual({
+      id: 1,
+      gameId: 100,
+      achievementIds: [1, 2, 3, 4, 5],
+      raPoints: 100,
+      consoleName: "PlayStation Portable"
+    });
+  });
+
+  it("can serialize an array of objects", () => {
+    // ARRANGE
+    const originalArray = [
+      {
+        ID: 1,
+        GameID: 100,
+        AchievementIDs: [1, 2, 3, 4, 5],
+        RAPoints: 100,
+        ConsoleName: "PlayStation Portable"
+      }
+    ];
+
+    // ACT
+    const sanitizedArray = serializeProperties(originalArray);
+
+    // ASSERT
+    expect(sanitizedArray).toEqual([
+      {
+        id: 1,
+        gameId: 100,
+        achievementIds: [1, 2, 3, 4, 5],
+        raPoints: 100,
+        consoleName: "PlayStation Portable"
+      }
+    ]);
+  });
+
+  it("can serialize an object that contains nested objects", () => {
+    // ARRANGE
+    const originalObject = {
+      ID: 1,
+      GameID: 100,
+      AchievementIDs: [1, 2, 3, 4, 5],
+      RAPoints: 100,
+      ConsoleName: "PlayStation Portable",
+      UserMeta: {
+        Name: "xelnia",
+        Points: 100
+      }
+    };
+
+    // ACT
+    const sanitizedObject = serializeProperties(originalObject);
+
+    // ASSERT
+    expect(sanitizedObject).toEqual({
+      id: 1,
+      gameId: 100,
+      achievementIds: [1, 2, 3, 4, 5],
+      raPoints: 100,
+      consoleName: "PlayStation Portable",
+      userMeta: {
+        name: "xelnia",
+        points: 100
+      }
+    });
+  });
+
+  it("can be instructed to cast values of certain keys to numbers", () => {
+    // ARRANGE
+    const originalObject = {
+      UserName: "xelnia",
+      Points: "500",
+      Metadata: {
+        TitleID: "100"
+      }
+    };
+
+    // ACT
+    const sanitizedObject = serializeProperties(originalObject, {
+      shouldCastToNumbers: ["TitleID", "Points"]
+    });
+
+    // ASSERT
+    expect(sanitizedObject).toEqual({
+      userName: "xelnia",
+      points: 500,
+      metadata: {
+        titleId: 100
+      }
+    });
+  });
+
+  it("can be instructed to map values of certain keys to booleans", () => {
+    // ARRANGE
+    const originalObject = {
+      UserName: "xelnia",
+      HardcoreMode: "0",
+      Metadata: {
+        IsCoolGuy: "1"
+      }
+    };
+
+    // ACT
+    const sanitizedObject = serializeProperties(originalObject, {
+      shouldMapToBooleans: ["HardcoreMode", "IsCoolGuy"]
+    });
+
+    // ASSERT
+    expect(sanitizedObject).toEqual({
+      userName: "xelnia",
+      hardcoreMode: false,
+      metadata: {
+        isCoolGuy: true
+      }
+    });
+  });
+});