@retroachievements/api 1.0.0-rc.0 → 1.0.0-rc.2

package/src/achievement/getAchievementUnlocks.test.ts

@@ -26,14 +26,30 @@ describe("Function: getAchievementUnlocks", () => {
       webApiKey: "mockWebApiKey"
     });
 
-    const mockResponse: GetAchievementUnlocksResponse = [
-      {
-        User: "Podgicus0305",
-        RAPoints: "15544",
-        DateAwarded: "2022-07-12 19:06:34",
-        HardcoreMode: "1"
-      }
-    ];
+    const mockResponse: GetAchievementUnlocksResponse = {
+      Achievement: {
+        ID: "1",
+        Title: "Ring Collector",
+        Description: "Collect 100 Rings!",
+        Points: "5",
+        TrueRatio: "6",
+        Author: "Scott",
+        DateCreated: "2012-11-02 00:03:12",
+        DateModified: "2022-06-11 16:52:35"
+      },
+      Console: { ID: "1", Title: "Mega Drive" },
+      Game: { ID: "1", Title: "Sonic the Hedgehog" },
+      UnlocksCount: 9524,
+      TotalPlayers: 21_710,
+      Unlocks: [
+        {
+          User: "Tiotroll2022",
+          RAPoints: "348",
+          DateAwarded: "2023-01-29 21:45:41",
+          HardcoreMode: "0"
+        }
+      ]
+    };
 
     let searchParams = "";
 
@@ -59,13 +75,29 @@ describe("Function: getAchievementUnlocks", () => {
     expect(searchParams).toContain("o=1");
     expect(searchParams).toContain("c=1");
 
-    expect(response).toEqual([
-      {
-        user: "Podgicus0305",
-        raPoints: 15_544,
-        dateAwarded: "2022-07-12 19:06:34",
-        hardcoreMode: true
-      }
-    ]);
+    expect(response).toEqual({
+      achievement: {
+        id: 1,
+        title: "Ring Collector",
+        description: "Collect 100 Rings!",
+        points: 5,
+        trueRatio: 6,
+        author: "Scott",
+        dateCreated: "2012-11-02 00:03:12",
+        dateModified: "2022-06-11 16:52:35"
+      },
+      console: { id: 1, title: "Mega Drive" },
+      game: { id: 1, title: "Sonic the Hedgehog" },
+      unlocksCount: 9524,
+      totalPlayers: 21_710,
+      unlocks: [
+        {
+          user: "Tiotroll2022",
+          raPoints: 348,
+          dateAwarded: "2023-01-29 21:45:41",
+          hardcoreMode: false
+        }
+      ]
+    });
   });
 });

package/src/achievement/getAchievementUnlocks.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -50,11 +51,11 @@ import type {
  */
 export const getAchievementUnlocks = async (
   authorization: AuthObject,
-  payload: { achievementId: number; offset?: number; count?: number }
+  payload: { achievementId: ID; offset?: number; count?: number }
 ): Promise<AchievementUnlockEntity[]> => {
   const { achievementId, offset, count } = payload;
 
-  const queryParams: Record<string, number> = { a: achievementId };
+  const queryParams: Record<string, number | string> = { a: achievementId };
 
   if (offset) {
     queryParams.o = offset;
@@ -74,7 +75,7 @@ export const getAchievementUnlocks = async (
   const rawResponse = await call<GetAchievementUnlocksResponse>({ url });
 
   return serializeProperties(rawResponse, {
-    shouldCastToNumbers: ["RAPoints"],
+    shouldCastToNumbers: ["ID", "Points", "TrueRatio", "RAPoints"],
     shouldMapToBooleans: ["HardcoreMode"]
   });
 };

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

@@ -4,3 +4,22 @@ export interface AchievementUnlockEntity {
   dateAwarded: string;
   hardcoreMode: boolean;
 }
+
+export interface AchievementUnlocksMetadata {
+  achievement: {
+    id: number;
+    title: string;
+    description: string;
+    points: number;
+    trueRatio: number;
+    author: string;
+    dateCreated: string;
+    dateModified: string;
+  };
+
+  console: { id: number; title: string };
+  game: { id: number; title: string };
+  unlocksCount: number;
+  totalPlayers: number;
+  unlocks: AchievementUnlockEntity[];
+}

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

@@ -5,4 +5,20 @@ interface AchievementUnlocksResponseEntity {
   HardcoreMode: string;
 }
 
-export type GetAchievementUnlocksResponse = AchievementUnlocksResponseEntity[];
+export interface GetAchievementUnlocksResponse {
+  Achievement: {
+    ID: string;
+    Title: string;
+    Description: string;
+    Points: string;
+    TrueRatio: string;
+    Author: string;
+    DateCreated: string;
+    DateModified: string;
+  };
+  Console: { ID: string; Title: string };
+  Game: { ID: string; Title: string };
+  UnlocksCount: number;
+  TotalPlayers: number;
+  Unlocks: AchievementUnlocksResponseEntity[];
+}

package/src/console/getGameList.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -6,7 +7,6 @@ import {
 } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { GameList, GetGameListResponse } from "./models";
-
 /**
  * A call to this function will retrieve the complete list
  * of games for a specified console on the RetroAchievements.org
@@ -55,7 +55,7 @@ import type { GameList, GetGameListResponse } from "./models";
 export const getGameList = async (
   authorization: AuthObject,
   payload: {
-    consoleId: number;
+    consoleId: ID;
     shouldOnlyRetrieveGamesWithAchievements?: boolean;
     shouldRetrieveGameHashes?: boolean;
   }

package/src/feed/getTicketData.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -51,7 +52,7 @@ interface GetTicketDataAllPayloadValues {
  */
 export function getTicketData(
   authorization: AuthObject,
-  payload: { ticketId: string | number }
+  payload: { ticketId: ID }
 ): Promise<TicketEntity>;
 
 /**
@@ -161,7 +162,7 @@ export function getTicketData(
 export function getTicketData(
   authorization: AuthObject,
   payload: {
-    gameId: string | number;
+    gameId: ID;
     isGettingTicketsForUnofficialAchievements?: true;
     shouldReturnTicketsList?: true;
   }
@@ -191,7 +192,7 @@ export function getTicketData(
  */
 export function getTicketData(
   authorization: AuthObject,
-  payload: { achievementId: string | number }
+  payload: { achievementId: ID }
 ): Promise<AchievementTicketStats>;
 
 /**

package/src/feed/models/most-ticketed-games.model.ts

@@ -1,4 +1,4 @@
-interface ReportedGameEntity {
+export interface ReportedGameEntity {
   gameId: number;
   gameTitle: string;
   gameIcon: string;

package/src/game/getAchievementCount.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -35,7 +36,7 @@ import type { AchievementCount, GetAchievementCountResponse } from "./models";
  */
 export const getAchievementCount = async (
   authorization: AuthObject,
-  payload: { gameId: number }
+  payload: { gameId: ID }
 ): Promise<AchievementCount> => {
   const { gameId } = payload;
 

package/src/game/getAchievementDistribution.test.ts

@@ -4,10 +4,8 @@ import { setupServer } from "msw/node";
 import { apiBaseUrl } from "../utils/internal";
 import { buildAuthorization } from "../utils/public";
 import { getAchievementDistribution } from "./getAchievementDistribution";
-import {
-  type GetAchievementDistributionResponse,
-  AchievementDistributionFlags
-} from "./models";
+import type { GetAchievementDistributionResponse } from "./models";
+import { AchievementDistributionFlags } from "./models";
 
 const server = setupServer();
 

package/src/game/getAchievementDistribution.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import { apiBaseUrl, buildRequestUrl, call } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type {
@@ -58,7 +59,7 @@ import type {
 export const getAchievementDistribution = async (
   authorization: AuthObject,
   payload: {
-    gameId: number;
+    gameId: ID;
     flags?: AchievementDistributionFlags;
     hardcore?: boolean;
   }

package/src/game/getGame.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -52,7 +53,7 @@ import type { Game, GetGameResponse } from "./models";
  */
 export const getGame = async (
   authorization: AuthObject,
-  payload: { gameId: number }
+  payload: { gameId: ID }
 ): Promise<Game> => {
   const { gameId } = payload;
 

package/src/game/getGameExtended.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -72,7 +73,7 @@ import type { GameExtended, GetGameExtendedResponse } from "./models";
  */
 export const getGameExtended = async (
   authorization: AuthObject,
-  payload: { gameId: number }
+  payload: { gameId: ID }
 ): Promise<GameExtended> => {
   const { gameId } = payload;
 

package/src/game/getGameRankAndScore.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -44,7 +45,7 @@ import type {
  */
 export const getGameRankAndScore = async (
   authorization: AuthObject,
-  payload: { gameId: number; type: "latest-masters" | "high-scores" }
+  payload: { gameId: ID; type: "latest-masters" | "high-scores" }
 ): Promise<GameRankAndScoreEntity[]> => {
   const { gameId, type } = payload;
 

package/src/game/getGameRating.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -42,7 +43,7 @@ import type { GameRating, GetGameRatingResponse } from "./models";
  */
 export const getGameRating = async (
   authorization: AuthObject,
-  payload: { gameId: number }
+  payload: { gameId: ID }
 ): Promise<GameRating> => {
   const { gameId } = payload;
 

package/src/user/getAchievementsEarnedBetween.ts

@@ -41,25 +41,25 @@ import type {
  * @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'
- *    }
- *  ]
+ * [
+ *   {
+ *     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 (

package/src/user/getGameInfoAndUserProgress.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -86,7 +87,7 @@ import type {
  */
 export const getGameInfoAndUserProgress = async (
   authorization: AuthObject,
-  payload: { gameId: number; userName: string }
+  payload: { gameId: ID; userName: string }
 ): Promise<GameInfoAndUserProgress> => {
   const { gameId, userName } = payload;
 

package/src/user/getUserClaims.ts

@@ -22,7 +22,7 @@ import type { GetUserClaimsResponse, UserClaims } from "./models";
  * ```
  * const userClaims = await getUserClaims(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { userName: "Jamiras" }
  * );
  * ```
  *

package/src/user/getUserCompletedGames.ts

@@ -15,7 +15,7 @@ import type {
  * about the games a given user has played. It returns two
  * entries per each game: one for the softcore completion and
  * one for the hardcore completion. These are designated by
- * the `hardcoreMode` property on the completion object.
+ * the `hardcoreMode` property on each completion object.
  *
  * @param authorization An object containing your userName and webApiKey.
  * This can be constructed with `buildAuthorization()`.

package/src/user/getUserGameRankAndScore.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -50,7 +51,7 @@ import type {
  */
 export const getUserGameRankAndScore = async (
   authorization: AuthObject,
-  payload: { gameId: number; userName: string }
+  payload: { gameId: ID; userName: string }
 ): Promise<UserGameRankAndScore> => {
   const { gameId, userName } = payload;
 

package/src/user/getUserPoints.ts

@@ -14,7 +14,7 @@ import type { GetUserPointsResponse, UserPoints } from "./models";
  * @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 points for.
+ * @param payload.userName The user for which to retrieve the point totals for.
  *
  * @example
  * ```

package/src/user/getUserProgress.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import {
   apiBaseUrl,
   buildRequestUrl,
@@ -9,14 +10,14 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
 
 /**
  * A call to this function will retrieve a given user's
- * progress on a given set of games, targeted by game ID.
+ * progress on a given list of games, targeted by game ID.
  *
  * @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.gameIds An array of RetroAchievements Game IDs. If you aren't
+ * @param payload.gameIds An array of RetroAchievements game IDs. If you aren't
  * sure of the game ID, visit the game's page on the website and copy the number
  * at the end of the URL.
  *
@@ -24,7 +25,7 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
  * ```
  * const userProgress = await getUserProgress(
  *   authorization,
- *   { userName: "xelnia", gameIds: [14402, 1] }
+ *   { userName: "xelnia", gameIds: [1, 14402] }
  * );
  * ```
  *
@@ -52,7 +53,7 @@ import type { GetUserProgressResponse, UserProgress } from "./models";
  */
 export const getUserProgress = async (
   authorization: AuthObject,
-  payload: { userName: string; gameIds: Array<number | string> }
+  payload: { userName: string; gameIds: ID[] }
 ): Promise<UserProgress> => {
   const { userName, gameIds } = payload;
 

package/src/user/getUserRecentlyPlayedGames.test.ts

@@ -39,7 +39,8 @@ describe("Function: getUserRecentlyPlayedGames", () => {
         NumAchieved: 0,
         ScoreAchieved: 0,
         NumAchievedHardcore: 0,
-        ScoreAchievedHardcore: 0
+        ScoreAchievedHardcore: 0,
+        MyVote: "2"
       }
     ];
 
@@ -69,7 +70,8 @@ describe("Function: getUserRecentlyPlayedGames", () => {
         numAchieved: 0,
         scoreAchieved: 0,
         numAchievedHardcore: 0,
-        scoreAchievedHardcore: 0
+        scoreAchievedHardcore: 0,
+        myVote: 2
       }
     ]);
   });

package/src/user/getUserRecentlyPlayedGames.ts

@@ -87,7 +87,8 @@ export const getUserRecentlyPlayedGames = async (
       "NumAchieved",
       "ScoreAchieved",
       "NumAchievedHardcore",
-      "ScoreAchievedHardcore"
+      "ScoreAchievedHardcore",
+      "MyVote"
     ]
   });
 };

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

@@ -5,6 +5,7 @@ interface UserRecentlyPlayedGameResponseEntity {
   Title: string;
   ImageIcon: string;
   LastPlayed: string;
+  MyVote: "1" | "2" | "3" | "4" | "5" | null;
   NumPossibleAchievements: string;
   PossibleScore: string;
   NumAchieved: string | number;

package/src/user/models/user-completed-games.model.ts

@@ -1,4 +1,4 @@
-interface UserCompletedGame {
+export interface UserCompletedGame {
   gameId: number;
   title: string;
   imageIcon: string;

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

@@ -1,4 +1,4 @@
-interface UserGameRankAndScoreEntity {
+export interface UserGameRankAndScoreEntity {
   user: string;
   totalScore: number;
   lastAward: string;

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

@@ -1,4 +1,4 @@
-interface UserProgressEntity {
+export interface UserProgressEntity {
   numPossibleAchievements: number;
   possibleScore: number;
   numAchieved: number;

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

@@ -1,10 +1,11 @@
-interface UserRecentlyPlayedGameEntity {
+export interface UserRecentlyPlayedGameEntity {
   gameId: number;
   consoleId: number;
   consoleName: string;
   title: string;
   imageIcon: string;
   lastPlayed: string;
+  myVote: 1 | 2 | 3 | 4 | 5 | null;
   numPossibleAchievements: number;
   possibleScore: number;
   numAchieved: number;

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

@@ -1,4 +1,4 @@
-interface RecentlyPlayedGameEntity {
+export interface RecentlyPlayedGameEntity {
   gameId: number;
   consoleId: number;
   consoleName: string;
@@ -7,7 +7,7 @@ interface RecentlyPlayedGameEntity {
   lastPlayed: string;
 }
 
-interface LastActivityEntity {
+export interface LastActivityEntity {
   id: number;
   timestamp: string;
   lastupdate: string;
@@ -17,7 +17,7 @@ interface LastActivityEntity {
   data2: string;
 }
 
-interface LastGameEntity {
+export interface LastGameEntity {
   id: number;
   title: string;
   consoleId: number;
@@ -36,7 +36,7 @@ interface LastGameEntity {
   richPresencePatch: string;
 }
 
-interface AwardedGameEntity {
+export interface AwardedGameEntity {
   numPossibleAchievements: number;
   possibleScore: number;
   numAchieved: number;
@@ -45,7 +45,7 @@ interface AwardedGameEntity {
   scoreAchievedHardcore: number;
 }
 
-interface ExtendedRecentAchievementEntity {
+export interface ExtendedRecentAchievementEntity {
   id: number;
   gameId: number;
   gameTitle: string;

package/src/utils/internal/id.model.ts

@@ -0,0 +1 @@
+export type ID = string | number;

package/src/utils/internal/index.ts

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

package/src/utils/internal/serializeProperties.ts

@@ -26,7 +26,7 @@ export const serializeProperties = (
     for (const [originalKey, originalValue] of Object.entries(originalData)) {
       let sanitizedValue = originalValue;
       if (shouldCastToNumbers?.includes(originalKey)) {
-        sanitizedValue = Number(originalValue);
+        sanitizedValue = originalValue === null ? null : Number(originalValue);
       }
 
       if (shouldMapToBooleans?.includes(originalKey)) {