@retroachievements/api 2.0.0 → 2.2.0

package/src/game/getGameHashes.test.ts

@@ -0,0 +1,77 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getGameHashes } from "./getGameHashes";
+import type { GetGameHashesResponse } 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(getGameHashes).toBeDefined();
+  });
+
+  it("given a game ID, retrieves extended metadata about the game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetGameHashesResponse = {
+      Results: [
+        {
+          Name: "Sonic The Hedgehog (USA, Europe) (Ru) (NewGame).md",
+          MD5: "1b1d9ac862c387367e904036114c4825",
+          Labels: ["nointro", "rapatches"],
+          PatchUrl:
+            "https://github.com/RetroAchievements/RAPatches/raw/main/MD/Translation/Russian/1-Sonic1-Russian.zip",
+        },
+        {
+          Name: "Sonic The Hedgehog (USA, Europe).md",
+          MD5: "1bc674be034e43c96b86487ac69d9293",
+          Labels: ["nointro"],
+          PatchUrl: null,
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetGameHashes.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getGameHashes(authorization, { gameId: 1 });
+
+    // ASSERT
+    expect(response).toEqual({
+      results: [
+        {
+          name: "Sonic The Hedgehog (USA, Europe) (Ru) (NewGame).md",
+          md5: "1b1d9ac862c387367e904036114c4825",
+          labels: ["nointro", "rapatches"],
+          patchUrl:
+            "https://github.com/RetroAchievements/RAPatches/raw/main/MD/Translation/Russian/1-Sonic1-Russian.zip",
+        },
+        {
+          name: "Sonic The Hedgehog (USA, Europe).md",
+          md5: "1bc674be034e43c96b86487ac69d9293",
+          labels: ["nointro"],
+          patchUrl: null,
+        },
+      ],
+    });
+  });
+});

package/src/game/getGameHashes.ts

@@ -0,0 +1,66 @@
+import type { ID } from "../utils/internal";
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties,
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GameHashes, GetGameHashesResponse } from "./models";
+
+/**
+ * A call to this function will retrieve a list of hashes linked to a game.
+ *
+ * @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 getGameHashes(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object containing a list of game hashes.
+ * ```json
+ * {
+ *   "Results": [
+ *     {
+ *       "MD5": "1b1d9ac862c387367e904036114c4825",
+ *       "Name": "Sonic The Hedgehog (USA, Europe) (Ru) (NewGame).md",
+ *       "Labels": ["nointro", "rapatches"],
+ *       "PatchUrl": "https://github.com/RetroAchievements/RAPatches/raw/main/MD/Translation/Russian/1-Sonic1-Russian.zip"
+ *     },
+ *     {
+ *       "MD5": "1bc674be034e43c96b86487ac69d9293",
+ *       "Name": "Sonic The Hedgehog (USA, Europe).md",
+ *       "Labels": ["nointro"],
+ *       "PatchUrl": null
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const getGameHashes = async (
+  authorization: AuthObject,
+  payload: { gameId: ID }
+): Promise<GameHashes> => {
+  const { gameId } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetGameHashes.php",
+    authorization,
+    { i: gameId }
+  );
+
+  const rawResponse = await call<GetGameHashesResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/game/index.ts

@@ -2,6 +2,7 @@ export * from "./getAchievementCount";
 export * from "./getAchievementDistribution";
 export * from "./getGame";
 export * from "./getGameExtended";
+export * from "./getGameHashes";
 export * from "./getGameRankAndScore";
 export * from "./getGameRating";
 export * from "./models";

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

@@ -0,0 +1,10 @@
+interface GameHash {
+  md5: string;
+  name: string;
+  labels: string[];
+  patchUrl: string;
+}
+
+export interface GameHashes {
+  results: GameHash[];
+}

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

@@ -0,0 +1,10 @@
+interface GameHashResult {
+  MD5: string;
+  Name: string;
+  Labels: string[];
+  PatchUrl: string;
+}
+
+export interface GetGameHashesResponse {
+  Results: GameHashResult[];
+}

package/src/game/models/index.ts

@@ -4,11 +4,13 @@ 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-hashes.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-hashes-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/user/models/game-info-and-user-progress.model.ts

@@ -2,6 +2,7 @@ import type {
   GameExtended,
   GameExtendedAchievementEntity,
 } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 
 export type GameExtendedAchievementEntityWithUserProgress =
   GameExtendedAchievementEntity & {
@@ -17,11 +18,6 @@ export interface GameInfoAndUserProgress extends GameExtended {
   userCompletion: string;
   userCompletionHardcore: string;
 
-  highestAwardKind?:
-    | "mastered"
-    | "completed"
-    | "beaten-hardcore"
-    | "beaten-softcore"
-    | null;
+  highestAwardKind?: AwardKind | null;
   highestAwardDate?: string;
 }

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

@@ -2,6 +2,7 @@ import type {
   GameExtendedRawAchievementEntity,
   GetGameExtendedResponse,
 } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 
 type GetGameExtendedResponseWithoutClaims = Omit<
   GetGameExtendedResponse,
@@ -26,11 +27,6 @@ export interface GetGameInfoAndUserProgressResponse
   UserCompletion: string;
   UserCompletionHardcore: string;
 
-  HighestAwardKind?:
-    | "mastered"
-    | "completed"
-    | "beaten-hardcore"
-    | "beaten-softcore"
-    | null;
+  HighestAwardKind?: AwardKind | null;
   HighestAwardDate?: string;
 }

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

@@ -1,3 +1,5 @@
+import type { AwardKind } from "../../utils/public";
+
 interface RawUserCompletionProgressEntity {
   GameID: number;
   Title: string;
@@ -9,12 +11,7 @@ interface RawUserCompletionProgressEntity {
   NumAwardedHardcore: number;
 
   MostRecentAwardedDate?: string;
-  HighestAwardKind?:
-    | "mastered"
-    | "completed"
-    | "beaten-hardcore"
-    | "beaten-softcore"
-    | null;
+  HighestAwardKind?: AwardKind | null;
   HighestAwardDate?: string | null;
 }
 

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

@@ -1,3 +1,5 @@
+import type { AwardKind } from "../../utils/public";
+
 export interface UserCompletionProgressEntity {
   gameId: number;
   title: string;
@@ -9,11 +11,6 @@ export interface UserCompletionProgressEntity {
   numAwardedHardcore: number;
 
   mostRecentAwardedDate?: string;
-  highestAwardKind?:
-    | "mastered"
-    | "completed"
-    | "beaten-hardcore"
-    | "beaten-softcore"
-    | null;
+  highestAwardKind?: AwardKind | null;
   highestAwardDate?: string;
 }

package/src/utils/public/models/award-kind.model.ts

@@ -0,0 +1,5 @@
+export type AwardKind =
+  | "beaten-softcore"
+  | "beaten-hardcore"
+  | "completed"
+  | "mastered";

package/src/utils/public/models/index.ts

@@ -1 +1,2 @@
 export * from "./auth-object.model";
+export * from "./award-kind.model";