@retroachievements/api 1.3.0 → 1.4.0

package/dist/user/models/index.d.ts

@@ -5,8 +5,10 @@ export * from "./game-info-and-user-progress.model";
 export * from "./get-game-info-and-user-progress-response.model";
 export * from "./get-user-awards-response.model";
 export * from "./get-user-completed-games-response.model";
+export * from "./get-user-completion-progress-response.model";
 export * from "./get-user-game-rank-and-score-response.model";
 export * from "./get-user-points-response.model";
+export * from "./get-user-profile-response.model";
 export * from "./get-user-progress-response.model";
 export * from "./get-user-recent-achievements-response.model";
 export * from "./get-user-recently-played-games-response.model";
@@ -15,8 +17,11 @@ export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
 export * from "./user-completed-games.model";
+export * from "./user-completion-progress.model";
+export * from "./user-completion-progress-entity.model";
 export * from "./user-game-rank-and-score.model";
 export * from "./user-points.model";
+export * from "./user-profile.model";
 export * from "./user-progress.model";
 export * from "./user-recent-achievement.model";
 export * from "./user-recently-played-games.model";

package/dist/user/models/user-completion-progress-entity.model.d.ts

@@ -0,0 +1,13 @@
+export interface UserCompletionProgressEntity {
+    gameId: number;
+    title: string;
+    imageIcon: string;
+    consoleId: number;
+    consoleName: string;
+    maxPossible: number;
+    numAwarded: number;
+    numAwardedHardcore: number;
+    mostRecentAwardedDate?: string;
+    highestAwardKind?: "mastered" | "completed" | "beaten-hardcore" | "beaten-softcore" | null;
+    highestAwardDate?: string;
+}

package/dist/user/models/user-completion-progress.model.d.ts

@@ -0,0 +1,6 @@
+import type { UserCompletionProgressEntity } from "./user-completion-progress-entity.model";
+export interface UserCompletionProgress {
+    count: number;
+    total: number;
+    results: UserCompletionProgressEntity[];
+}

package/dist/user/models/user-profile.model.d.ts

@@ -0,0 +1,17 @@
+export interface UserProfile {
+    user: string;
+    userPic: string;
+    memberSince: string;
+    richPresenceMsg: string;
+    lastGameId: number;
+    contribCount: number;
+    contribYield: number;
+    totalPoints: number;
+    totalSoftcorePoints: number;
+    totalTruePoints: number;
+    permissions: number;
+    untracked: boolean;
+    id: number;
+    userWallActive: boolean;
+    motto: string;
+}

package/package.json

@@ -10,7 +10,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "1.3.0",
+  "version": "1.4.0",
   "typings": "dist/index.d.ts",
   "exports": {
     ".": {

package/src/game/getGame.test.ts

@@ -73,7 +73,7 @@ describe("Function: getGame", () => {
       publisher: "Activision ",
       developer: "David Crane",
       genre: "Racing",
-      released: 1980,
+      released: "1980",
       gameTitle: "Dragster",
       console: "Atari 2600"
     });

package/src/game/getGame.ts

@@ -45,7 +45,7 @@ import type { Game, GetGameResponse } from "./models";
  *   publisher: "Activision",
  *   developer: "David Crane",
  *   genre: "Racing",
- *   released: 1980,
+ *   released: "1980",
  *   gameTitle: "Dragster",
  *   console: "Atari 2600"
  * }
@@ -64,12 +64,6 @@ export const getGame = async (
   const rawResponse = await call<GetGameResponse>({ url });
 
   return serializeProperties(rawResponse, {
-    shouldCastToNumbers: [
-      "ID",
-      "ForumTopicID",
-      "ConsoleID",
-      "Flags",
-      "Released"
-    ]
+    shouldCastToNumbers: ["ID", "ForumTopicID", "ConsoleID", "Flags"]
   });
 };

package/src/game/getGameExtended.test.ts

@@ -91,7 +91,7 @@ describe("Function: getGameExtended", () => {
       publisher: "Activision ",
       developer: "David Crane",
       genre: "Racing",
-      released: 1980,
+      released: "1980",
       isFinal: false,
       consoleName: "Atari 2600",
       richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",

package/src/game/getGameExtended.ts

@@ -43,7 +43,7 @@ import type { GameExtended, GetGameExtendedResponse } from "./models";
  *   publisher: "Activision",
  *   developer: "David Crane",
  *   genre: "Racing",
- *   released: 1980,
+ *   released: "1980",
  *   isFinal: false,
  *   consoleName: "Atari 2600",
  *   richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
@@ -73,17 +73,23 @@ import type { GameExtended, GetGameExtendedResponse } from "./models";
  */
 export const getGameExtended = async (
   authorization: AuthObject,
-  payload: { gameId: ID }
+  payload: { gameId: ID; isRequestingUnofficialAchievements: boolean }
 ): Promise<GameExtended> => {
-  const { gameId } = payload;
+  const { gameId, isRequestingUnofficialAchievements } = payload;
+
+  const params: Record<string, string | number> = {
+    i: gameId
+  };
+
+  if (isRequestingUnofficialAchievements) {
+    params["f"] = 5;
+  }
 
   const url = buildRequestUrl(
     apiBaseUrl,
     "/API_GetGameExtended.php",
     authorization,
-    {
-      i: gameId
-    }
+    params
   );
 
   const rawResponse = await call<GetGameExtendedResponse>({ url });
@@ -97,8 +103,7 @@ export const getGameExtended = async (
       "TrueRatio",
       "DisplayOrder",
       "NumDistinctPlayersCasual",
-      "NumDistinctPlayersHardcore",
-      "Released"
+      "NumDistinctPlayersHardcore"
     ]
   });
 };

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

@@ -14,7 +14,7 @@ export interface GameExtended {
   publisher: string;
   developer: string;
   genre: string;
-  released: number;
+  released: string;
   isFinal: boolean;
   consoleName: string;
   richPresencePatch: string;

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

@@ -13,7 +13,7 @@ export interface Game {
   publisher: string;
   developer: string;
   genre: string;
-  released: number;
+  released: string;
   gameTitle: string;
   console: string;
 }

package/src/user/getUserCompletionProgress.test.ts

@@ -0,0 +1,81 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserCompletionProgress } from "./getUserCompletionProgress";
+import type { GetUserCompletionProgressResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserCompletionProgress", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserCompletionProgress).toBeDefined();
+  });
+
+  it("retrieves completion progress by username", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserCompletionProgressResponse = {
+      Count: 1,
+      Total: 1,
+      Results: [
+        {
+          GameID: 680,
+          Title: "Game & Watch Gallery",
+          ImageIcon: "/Images/042952.png",
+          ConsoleID: 4,
+          ConsoleName: "Game Boy",
+          MaxPossible: 27,
+          NumAwarded: 8,
+          NumAwardedHardcore: 8,
+          MostRecentAwardedDate: "2022-07-26T23:56:15+00:00",
+          HighestAwardKind: null,
+          HighestAwardDate: null
+        }
+      ]
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUserCompletionProgress.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getUserCompletionProgress(authorization, {
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      count: 1,
+      total: 1,
+      results: [
+        {
+          gameId: 680,
+          title: "Game & Watch Gallery",
+          imageIcon: "/Images/042952.png",
+          consoleId: 4,
+          consoleName: "Game Boy",
+          maxPossible: 27,
+          numAwarded: 8,
+          numAwardedHardcore: 8,
+          mostRecentAwardedDate: "2022-07-26T23:56:15+00:00",
+          highestAwardKind: null,
+          highestAwardDate: null
+        }
+      ]
+    });
+  });
+});

package/src/user/getUserCompletionProgress.ts

@@ -0,0 +1,83 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserCompletionProgressResponse,
+  UserCompletionProgress
+} from "./models";
+
+/**
+ * A call to this function will retrieve a given user's completion
+ * progress, targeted by their username.
+ *
+ * @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 progress for.
+ *
+ * @param payload.offset Defaults to 0. The number of entries to skip.
+ *
+ * @param payload.count Defaults to 100, has a max of 500.
+ *
+ * @example
+ * ```
+ * const userCompletionProgress = await getUserCompletionProgress(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns
+ * ```
+ * {
+ *   "count": 100,
+ *   "total": 752,
+ *   "results": [
+ *     {
+         gameId: 11406,
+         title: 'Mortal Kombat 4',
+         imageIcon: '/Images/042133.png',
+         consoleId: 12,
+         consoleName: 'PlayStation',
+         maxPossible: 131,
+         numAwarded: 131,
+         numAwardedHardcore: 131,
+         mostRecentAwardedDate: '2022-08-07T18:24:44+00:00',
+         highestAwardKind: 'mastered',
+         highestAwardDate: '2022-08-07T18:24:44+00:00'
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const getUserCompletionProgress = async (
+  authorization: AuthObject,
+  payload: { userName: string; offset?: number; count?: number }
+): Promise<UserCompletionProgress> => {
+  const { userName, offset, count } = payload;
+
+  const params: Record<string, string | number> = {
+    u: userName
+  };
+  if (offset) {
+    params["o"] = offset;
+  }
+  if (count) {
+    params["c"] = count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserCompletionProgress.php",
+    authorization,
+    params
+  );
+
+  const rawResponse = await call<GetUserCompletionProgressResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/user/getUserProfile.test.ts

@@ -0,0 +1,79 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserProfile } from "./getUserProfile";
+import type { GetUserProfileResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserProfile", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserProfile).toBeDefined();
+  });
+
+  it("given a username, retrieves minimal user profile information about the user", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserProfileResponse = {
+      User: "MaxMilyin",
+      UserPic: "/UserPic/MaxMilyin.png",
+      MemberSince: "2016-01-02 00:43:04",
+      RichPresenceMsg:
+        "Playing ~Hack~ 11th Annual Vanilla Level Design Contest, The",
+      LastGameID: 19_504,
+      ContribCount: 0,
+      ContribYield: 0,
+      TotalPoints: 399_597,
+      TotalSoftcorePoints: 0,
+      TotalTruePoints: 1_599_212,
+      Permissions: 1,
+      Untracked: 0,
+      ID: 16_446,
+      UserWallActive: 1,
+      Motto: "Join me on Twitch! GameSquadSquad for live RA"
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUserProfile.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getUserProfile(authorization, {
+      userName: "WCopeland"
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      user: "MaxMilyin",
+      userPic: "/UserPic/MaxMilyin.png",
+      memberSince: "2016-01-02 00:43:04",
+      richPresenceMsg:
+        "Playing ~Hack~ 11th Annual Vanilla Level Design Contest, The",
+      lastGameId: 19_504,
+      contribCount: 0,
+      contribYield: 0,
+      totalPoints: 399_597,
+      totalSoftcorePoints: 0,
+      totalTruePoints: 1_599_212,
+      permissions: 1,
+      untracked: false,
+      id: 16_446,
+      userWallActive: true,
+      motto: "Join me on Twitch! GameSquadSquad for live RA"
+    });
+  });
+});

package/src/user/getUserProfile.ts

@@ -0,0 +1,55 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GetUserProfileResponse, UserProfile } from "./models";
+
+/**
+ * A call to this function will retrieve summary information about
+ * a given user, targeted by username.
+ *
+ * @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 summary for.
+ *
+ * @example
+ * ```
+ * const userSummary = await getUserProfile(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing profile summary metadata about a target user.
+ */
+export const getUserProfile = async (
+  authorization: AuthObject,
+  payload: {
+    userName: string;
+  }
+): Promise<UserProfile> => {
+  const { userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserProfile.php",
+    authorization,
+    { u: userName }
+  );
+
+  const rawResponse = await call<GetUserProfileResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "TotalPoints",
+      "TotalSoftcorePoints",
+      "TotalTruePoints",
+      "Permissions"
+    ],
+    shouldMapToBooleans: ["Untracked", "UserWallActive"]
+  });
+};

package/src/user/index.ts

@@ -4,8 +4,10 @@ export * from "./getGameInfoAndUserProgress";
 export * from "./getUserAwards";
 export * from "./getUserClaims";
 export * from "./getUserCompletedGames";
+export * from "./getUserCompletionProgress";
 export * from "./getUserGameRankAndScore";
 export * from "./getUserPoints";
+export * from "./getUserProfile";
 export * from "./getUserProgress";
 export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";

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

@@ -0,0 +1,25 @@
+interface RawUserCompletionProgressEntity {
+  GameID: number;
+  Title: string;
+  ImageIcon: string;
+  ConsoleID: number;
+  ConsoleName: string;
+  MaxPossible: number;
+  NumAwarded: number;
+  NumAwardedHardcore: number;
+
+  MostRecentAwardedDate?: string;
+  HighestAwardKind?:
+    | "mastered"
+    | "completed"
+    | "beaten-hardcore"
+    | "beaten-softcore"
+    | null;
+  HighestAwardDate?: string | null;
+}
+
+export interface GetUserCompletionProgressResponse {
+  Count: number;
+  Total: number;
+  Results: RawUserCompletionProgressEntity[];
+}

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

@@ -0,0 +1,17 @@
+export interface GetUserProfileResponse {
+  User: string;
+  UserPic: string;
+  MemberSince: string;
+  RichPresenceMsg: string;
+  LastGameID: number;
+  ContribCount: number;
+  ContribYield: number;
+  TotalPoints: number;
+  TotalSoftcorePoints: number;
+  TotalTruePoints: number;
+  Permissions: number;
+  Untracked: number;
+  ID: number;
+  UserWallActive: number;
+  Motto: string;
+}

package/src/user/models/index.ts

@@ -5,8 +5,10 @@ export * from "./game-info-and-user-progress.model";
 export * from "./get-game-info-and-user-progress-response.model";
 export * from "./get-user-awards-response.model";
 export * from "./get-user-completed-games-response.model";
+export * from "./get-user-completion-progress-response.model";
 export * from "./get-user-game-rank-and-score-response.model";
 export * from "./get-user-points-response.model";
+export * from "./get-user-profile-response.model";
 export * from "./get-user-progress-response.model";
 export * from "./get-user-recent-achievements-response.model";
 export * from "./get-user-recently-played-games-response.model";
@@ -15,8 +17,11 @@ export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
 export * from "./user-completed-games.model";
+export * from "./user-completion-progress.model";
+export * from "./user-completion-progress-entity.model";
 export * from "./user-game-rank-and-score.model";
 export * from "./user-points.model";
+export * from "./user-profile.model";
 export * from "./user-progress.model";
 export * from "./user-recent-achievement.model";
 export * from "./user-recently-played-games.model";

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

@@ -0,0 +1,19 @@
+export interface UserCompletionProgressEntity {
+  gameId: number;
+  title: string;
+  imageIcon: string;
+  consoleId: number;
+  consoleName: string;
+  maxPossible: number;
+  numAwarded: number;
+  numAwardedHardcore: number;
+
+  mostRecentAwardedDate?: string;
+  highestAwardKind?:
+    | "mastered"
+    | "completed"
+    | "beaten-hardcore"
+    | "beaten-softcore"
+    | null;
+  highestAwardDate?: string;
+}

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

@@ -0,0 +1,7 @@
+import type { UserCompletionProgressEntity } from "./user-completion-progress-entity.model";
+
+export interface UserCompletionProgress {
+  count: number;
+  total: number;
+  results: UserCompletionProgressEntity[];
+}

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

@@ -0,0 +1,17 @@
+export interface UserProfile {
+  user: string;
+  userPic: string;
+  memberSince: string;
+  richPresenceMsg: string;
+  lastGameId: number;
+  contribCount: number;
+  contribYield: number;
+  totalPoints: number;
+  totalSoftcorePoints: number;
+  totalTruePoints: number;
+  permissions: number;
+  untracked: boolean;
+  id: number;
+  userWallActive: boolean;
+  motto: string;
+}