@retroachievements/api 2.0.0 → 2.2.0

package/dist/feed/getRecentGameAwards.d.ts

@@ -0,0 +1,50 @@
+import type { AuthObject, AwardKind } from "../utils/public";
+import type { RecentGameAwards } from "./models";
+/**
+ * A call to this function will retrieve all recently granted game
+ * awards across the site's userbase.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.startDate The date to fetch awards from.
+ *
+ * @param payload.offset Optional. Defaults to 0.
+ *
+ * @param payload.count Optional. Defaults to 25.
+ *
+ * @param payload.desiredAwardKinds Optional. Defaults to all. Accepts "beaten-softcore", "beaten-hardcore", "completed", and/or "mastered".
+ *
+ * @example
+ * ```
+ * const recentGameAwards = await getRecentGameAwards(
+ *   authorization,
+ * );
+ * ```
+ *
+ * @returns An object containing metadata about all recently granted game
+ * awards across the site's userbase
+ * ```
+ * {
+ *   count: 1,
+ *   total: 1,
+ *   results: [
+ *     {
+ *       user: "renanbrj",
+ *       awardKind: "mastered",
+ *       awardDate: "2022-01-01T23:48:04+00:00",
+ *       gameId: 14_284,
+ *       gameTitle: "Batman Returns",
+ *       consoleId: 15,
+ *       consoleName: "Game Gear",
+ *     },
+ *   ],
+ * }
+ * ```
+ */
+export declare const getRecentGameAwards: (authorization: AuthObject, payload?: Partial<{
+    startDate: string;
+    offset: number;
+    count: number;
+    desiredAwardKinds: AwardKind[];
+}>) => Promise<RecentGameAwards>;

package/dist/feed/getRecentGameAwards.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/feed/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./getAchievementOfTheWeek";
 export * from "./getActiveClaims";
 export * from "./getClaims";
+export * from "./getRecentGameAwards";
 export * from "./getTopTenUsers";
 export * from "./models";

package/dist/feed/models/achievement-of-the-week.model.d.ts

@@ -27,6 +27,7 @@ export interface AchievementOfTheWeek {
     unlocks: Array<{
         user: string;
         raPoints: number;
+        raSoftcorePoints: number;
         dateAwarded: string;
         hardcoreMode: boolean;
     }>;

package/dist/feed/models/get-achievement-of-the-week-response.model.d.ts

@@ -27,6 +27,7 @@ export interface GetAchievementOfTheWeekResponse {
     Unlocks: Array<{
         User: string;
         RAPoints: string;
+        RASoftcorePoints: string;
         DateAwarded: string;
         HardcoreMode: string;
     }>;

package/dist/feed/models/get-recent-game-awards-response.model.d.ts

@@ -0,0 +1,14 @@
+import type { AwardKind } from "../../utils/public";
+export interface GetRecentGameAwardsResponse {
+    Count: number;
+    Total: number;
+    Results: Array<{
+        User: string;
+        AwardKind: AwardKind;
+        AwardDate: string;
+        GameID: number;
+        GameTitle: string;
+        ConsoleID: number;
+        ConsoleName: string;
+    }>;
+}

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

@@ -3,8 +3,10 @@ export * from "./claim-set-type.enum";
 export * from "./claim-status.enum";
 export * from "./claim-type.enum";
 export * from "./get-achievement-of-the-week-response.model";
+export * from "./get-recent-game-awards-response.model";
 export * from "./get-set-claims-response.model";
 export * from "./get-top-ten-users-response.model";
+export * from "./recent-game-awards.model";
 export * from "./set-claim.model";
 export * from "./top-ten-users.model";
 export * from "./top-ten-users-entity.model";

package/dist/feed/models/recent-game-awards.model.d.ts

@@ -0,0 +1,14 @@
+import type { AwardKind } from "../../utils/public";
+export interface RecentGameAwards {
+    count: number;
+    total: number;
+    results: Array<{
+        user: string;
+        awardKind: AwardKind;
+        awardDate: string;
+        gameId: number;
+        gameTitle: string;
+        consoleId: number;
+        consoleName: string;
+    }>;
+}

package/dist/game/getGameHashes.d.ts

@@ -0,0 +1,45 @@
+import type { ID } from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GameHashes } 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 declare const getGameHashes: (authorization: AuthObject, payload: {
+    gameId: ID;
+}) => Promise<GameHashes>;

package/dist/game/getGameHashes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/game/index.d.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/dist/game/models/game-hashes.model.d.ts

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

package/dist/game/models/get-game-hashes-response.model.d.ts

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

package/dist/game/models/index.d.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/dist/user/models/game-info-and-user-progress.model.d.ts

@@ -1,4 +1,5 @@
 import type { GameExtended, GameExtendedAchievementEntity } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 export type GameExtendedAchievementEntityWithUserProgress = GameExtendedAchievementEntity & {
     dateEarned: string;
     dateEarnedHardcore: string;
@@ -9,6 +10,6 @@ export interface GameInfoAndUserProgress extends GameExtended {
     numAwardedToUserHardcore: number;
     userCompletion: string;
     userCompletionHardcore: string;
-    highestAwardKind?: "mastered" | "completed" | "beaten-hardcore" | "beaten-softcore" | null;
+    highestAwardKind?: AwardKind | null;
     highestAwardDate?: string;
 }

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

@@ -1,4 +1,5 @@
 import type { GameExtendedRawAchievementEntity, GetGameExtendedResponse } from "../../game/models";
+import type { AwardKind } from "../../utils/public";
 type GetGameExtendedResponseWithoutClaims = Omit<GetGameExtendedResponse, "Claims">;
 type GameExtendedRawAchievementEntityWithUserProgress = GameExtendedRawAchievementEntity & {
     DateEarned: string;
@@ -10,7 +11,7 @@ export interface GetGameInfoAndUserProgressResponse extends GetGameExtendedRespo
     NumAwardedToUserHardcore: number;
     UserCompletion: string;
     UserCompletionHardcore: string;
-    HighestAwardKind?: "mastered" | "completed" | "beaten-hardcore" | "beaten-softcore" | null;
+    HighestAwardKind?: AwardKind | null;
     HighestAwardDate?: string;
 }
 export {};

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

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

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

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

package/dist/utils/public/models/award-kind.model.d.ts

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

package/dist/utils/public/models/index.d.ts

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

package/package.json

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

package/src/achievement/getAchievementUnlocks.test.ts

@@ -45,6 +45,7 @@ describe("Function: getAchievementUnlocks", () => {
         {
           User: "Tiotroll2022",
           RAPoints: "348",
+          RASoftcorePoints: "363",
           DateAwarded: "2023-01-29 21:45:41",
           HardcoreMode: "0",
         },
@@ -91,6 +92,7 @@ describe("Function: getAchievementUnlocks", () => {
         {
           user: "Tiotroll2022",
           raPoints: 348,
+          raSoftcorePoints: 363,
           dateAwarded: "2023-01-29 21:45:41",
           hardcoreMode: false,
         },

package/src/achievement/getAchievementUnlocks.ts

@@ -75,7 +75,13 @@ export const getAchievementUnlocks = async (
   const rawResponse = await call<GetAchievementUnlocksResponse>({ url });
 
   return serializeProperties(rawResponse, {
-    shouldCastToNumbers: ["ID", "Points", "TrueRatio", "RAPoints"],
+    shouldCastToNumbers: [
+      "ID",
+      "Points",
+      "TrueRatio",
+      "RAPoints",
+      "RASoftcorePoints",
+    ],
     shouldMapToBooleans: ["HardcoreMode"],
   });
 };

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

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

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

@@ -1,6 +1,7 @@
 interface AchievementUnlocksResponseEntity {
   User: string;
   RAPoints: string;
+  RASoftcorePoints: string;
   DateAwarded: string;
   HardcoreMode: string;
 }

package/src/console/getConsoleIds.test.ts

@@ -62,7 +62,10 @@ describe("Function: getConsoleIds", () => {
     );
 
     // ACT
-    const response = await getConsoleIds(authorization);
+    const response = await getConsoleIds(authorization, {
+      shouldOnlyRetrieveActiveSystems: true,
+      shouldOnlyRetrieveGameSystems: true,
+    });
 
     // ASSERT
     const expectedResponse: FetchedSystem[] = [

package/src/feed/getAchievementOfTheWeek.test.ts

@@ -53,6 +53,7 @@ describe("Function: getAchievementOfTheWeek", () => {
         {
           User: "Tirbaba2",
           RAPoints: "72",
+          RASoftcorePoints: "72",
           DateAwarded: "2022-10-10 01:42:19",
           HardcoreMode: "1",
         },
@@ -91,6 +92,7 @@ describe("Function: getAchievementOfTheWeek", () => {
         {
           user: "Tirbaba2",
           raPoints: 72,
+          raSoftcorePoints: 72,
           dateAwarded: "2022-10-10 01:42:19",
           hardcoreMode: true,
         },
@@ -131,6 +133,7 @@ describe("Function: getAchievementOfTheWeek", () => {
         {
           User: "Tirbaba2",
           RAPoints: "72",
+          RASoftcorePoints: "72",
           DateAwarded: "2022-10-10 01:42:19",
           HardcoreMode: "0",
         },
@@ -169,6 +172,7 @@ describe("Function: getAchievementOfTheWeek", () => {
         {
           user: "Tirbaba2",
           raPoints: 72,
+          raSoftcorePoints: 72,
           dateAwarded: "2022-10-10 01:42:19",
           hardcoreMode: false,
         },

package/src/feed/getAchievementOfTheWeek.ts

@@ -48,7 +48,8 @@ import type {
  *   unlocks: [
  *     {
  *       user: "Tirbaba2",
- *       rAPoints: "72",
+ *       raPoints: "72",
+ *       raSoftcorePoints: "72",
  *       dateAwarded: "2022-10-10 01:42:19",
  *       hardcoreMode: "1"
  *     }
@@ -75,6 +76,7 @@ export const getAchievementOfTheWeek = async (
       "TrueRatio",
       "TotalPlayers",
       "RAPoints",
+      "RASoftcorePoints",
       "UnlocksCount",
     ],
     shouldMapToBooleans: ["HardcoreMode"],

package/src/feed/getRecentGameAwards.test.ts

@@ -0,0 +1,78 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getRecentGameAwards } from "./getRecentGameAwards";
+import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
+
+const server = setupServer();
+
+describe("Function: getRecentGameAwards", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getRecentGameAwards).toBeDefined();
+  });
+
+  it("retrieves metadata about all recently-earned game awards on the site", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetRecentGameAwardsResponse = {
+      Count: 1,
+      Total: 1,
+      Results: [
+        {
+          User: "renanbrj",
+          AwardKind: "mastered",
+          AwardDate: "2022-01-01T23:48:04+00:00",
+          GameID: 14_284,
+          GameTitle: "Batman Returns",
+          ConsoleID: 15,
+          ConsoleName: "Game Gear",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetRecentGameAwards.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getRecentGameAwards(authorization, {
+      startDate: "2025-01-05",
+      offset: 10,
+      count: 10,
+      desiredAwardKinds: ["completed"],
+    });
+
+    const expectedResponse: RecentGameAwards = {
+      count: 1,
+      total: 1,
+      results: [
+        {
+          user: "renanbrj",
+          awardKind: "mastered",
+          awardDate: "2022-01-01T23:48:04+00:00",
+          gameId: 14_284,
+          gameTitle: "Batman Returns",
+          consoleId: 15,
+          consoleName: "Game Gear",
+        },
+      ],
+    };
+
+    // ASSERT
+    expect(response).toEqual(expectedResponse);
+  });
+});

package/src/feed/getRecentGameAwards.ts

@@ -0,0 +1,85 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties,
+} from "../utils/internal";
+import type { AuthObject, AwardKind } from "../utils/public";
+import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
+
+/**
+ * A call to this function will retrieve all recently granted game
+ * awards across the site's userbase.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.startDate The date to fetch awards from.
+ *
+ * @param payload.offset Optional. Defaults to 0.
+ *
+ * @param payload.count Optional. Defaults to 25.
+ *
+ * @param payload.desiredAwardKinds Optional. Defaults to all. Accepts "beaten-softcore", "beaten-hardcore", "completed", and/or "mastered".
+ *
+ * @example
+ * ```
+ * const recentGameAwards = await getRecentGameAwards(
+ *   authorization,
+ * );
+ * ```
+ *
+ * @returns An object containing metadata about all recently granted game
+ * awards across the site's userbase
+ * ```
+ * {
+ *   count: 1,
+ *   total: 1,
+ *   results: [
+ *     {
+ *       user: "renanbrj",
+ *       awardKind: "mastered",
+ *       awardDate: "2022-01-01T23:48:04+00:00",
+ *       gameId: 14_284,
+ *       gameTitle: "Batman Returns",
+ *       consoleId: 15,
+ *       consoleName: "Game Gear",
+ *     },
+ *   ],
+ * }
+ * ```
+ */
+export const getRecentGameAwards = async (
+  authorization: AuthObject,
+  payload?: Partial<{
+    startDate: string;
+    offset: number;
+    count: number;
+    desiredAwardKinds: AwardKind[];
+  }>
+): Promise<RecentGameAwards> => {
+  const queryParams: Record<string, any> = {};
+  if (payload?.startDate) {
+    queryParams.d = payload.startDate;
+  }
+  if (payload?.offset) {
+    queryParams.o = payload.offset;
+  }
+  if (payload?.count) {
+    queryParams.c = payload.count;
+  }
+  if (payload?.desiredAwardKinds) {
+    queryParams.k = payload.desiredAwardKinds.join(",");
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetRecentGameAwards.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetRecentGameAwardsResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/feed/index.ts

@@ -1,5 +1,6 @@
 export * from "./getAchievementOfTheWeek";
 export * from "./getActiveClaims";
 export * from "./getClaims";
+export * from "./getRecentGameAwards";
 export * from "./getTopTenUsers";
 export * from "./models";

package/src/feed/models/achievement-of-the-week.model.ts

@@ -21,6 +21,7 @@ export interface AchievementOfTheWeek {
   unlocks: Array<{
     user: string;
     raPoints: number;
+    raSoftcorePoints: number;
     dateAwarded: string;
     hardcoreMode: boolean;
   }>;

package/src/feed/models/get-achievement-of-the-week-response.model.ts

@@ -21,6 +21,7 @@ export interface GetAchievementOfTheWeekResponse {
   Unlocks: Array<{
     User: string;
     RAPoints: string;
+    RASoftcorePoints: string;
     DateAwarded: string;
     HardcoreMode: string;
   }>;

package/src/feed/models/get-recent-game-awards-response.model.ts

@@ -0,0 +1,15 @@
+import type { AwardKind } from "../../utils/public";
+
+export interface GetRecentGameAwardsResponse {
+  Count: number;
+  Total: number;
+  Results: Array<{
+    User: string;
+    AwardKind: AwardKind;
+    AwardDate: string;
+    GameID: number;
+    GameTitle: string;
+    ConsoleID: number;
+    ConsoleName: string;
+  }>;
+}

package/src/feed/models/index.ts

@@ -3,8 +3,10 @@ export * from "./claim-set-type.enum";
 export * from "./claim-status.enum";
 export * from "./claim-type.enum";
 export * from "./get-achievement-of-the-week-response.model";
+export * from "./get-recent-game-awards-response.model";
 export * from "./get-set-claims-response.model";
 export * from "./get-top-ten-users-response.model";
+export * from "./recent-game-awards.model";
 export * from "./set-claim.model";
 export * from "./top-ten-users.model";
 export * from "./top-ten-users-entity.model";

package/src/feed/models/recent-game-awards.model.ts

@@ -0,0 +1,15 @@
+import type { AwardKind } from "../../utils/public";
+
+export interface RecentGameAwards {
+  count: number;
+  total: number;
+  results: Array<{
+    user: string;
+    awardKind: AwardKind;
+    awardDate: string;
+    gameId: number;
+    gameTitle: string;
+    consoleId: number;
+    consoleName: string;
+  }>;
+}