@retroachievements/api 0.0.0-development → 1.0.0-rc.0

package/dist/user/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./getAchievementsEarnedBetween";
 export * from "./getAchievementsEarnedOnDay";
 export * from "./getGameInfoAndUserProgress";
+export * from "./getUserClaims";
+export * from "./getUserCompletedGames";
 export * from "./getUserGameRankAndScore";
 export * from "./getUserPoints";
 export * from "./getUserProgress";

package/dist/user/models/get-user-completed-games-response.model.d.ts

@@ -0,0 +1,13 @@
+interface UserCompletedGamesResponseEntity {
+    GameID: string;
+    Title: string;
+    ImageIcon: string;
+    ConsoleID: string;
+    ConsoleName: string;
+    MaxPossible: string;
+    NumAwarded: string;
+    PctWon: string;
+    HardcoreMode: "0" | "1";
+}
+export declare type GetUserCompletedGamesResponse = UserCompletedGamesResponseEntity[];
+export {};

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

@@ -2,11 +2,15 @@ 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-completed-games-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-claims.model";
+export * from "./user-claims-response.model";
+export * from "./user-completed-games.model";
 export * from "./user-game-rank-and-score.model";
 export * from "./user-points.model";
 export * from "./user-progress.model";

package/dist/user/models/user-claims-response.model.d.ts

@@ -0,0 +1,19 @@
+interface UserClaimsResponseEntity {
+    ID: string;
+    User: string;
+    GameID: string;
+    GameTitle: string;
+    GameIcon: string;
+    ConsoleName: string;
+    ClaimType: string;
+    SetType: string;
+    Status: string;
+    Extension: string;
+    Special: string;
+    Created: string;
+    DoneTime: string;
+    Updated: string;
+    MinutesLeft: string;
+}
+export declare type GetUserClaimsResponse = UserClaimsResponseEntity[];
+export {};

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

@@ -0,0 +1,19 @@
+interface UserClaim {
+    id: number;
+    user: string;
+    gameId: number;
+    gameTitle: string;
+    gameIcon: string;
+    consoleName: string;
+    claimType: number;
+    setType: number;
+    status: number;
+    extension: number;
+    special: number;
+    created: string;
+    doneTime: string;
+    updated: string;
+    minutesLeft: number;
+}
+export declare type UserClaims = UserClaim[];
+export {};

package/dist/user/models/user-completed-games.model.d.ts

@@ -0,0 +1,13 @@
+interface UserCompletedGame {
+    gameId: number;
+    title: string;
+    imageIcon: string;
+    consoleId: number;
+    consoleName: string;
+    maxPossible: number;
+    numAwarded: number;
+    pctWon: number;
+    hardcoreMode: boolean;
+}
+export declare type UserCompletedGames = UserCompletedGame[];
+export {};

package/package.json

@@ -8,7 +8,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "0.0.0-development",
+  "version": "1.0.0-rc.0",
   "main": "dist/index.js",
   "module": "dist/api.esm.js",
   "typings": "dist/index.d.ts",

package/src/__playground.ts

@@ -7,7 +7,7 @@
 
 // If you can't import what you want from "./index", users won't
 // be able to import it either.
-import { buildAuthorization, getTicketData } from "./index";
+// import { buildAuthorization, getAchievementCount } from "./index";
 
 const main = async () => {
   console.log("retroachievements-api-js playground is running.");
@@ -15,13 +15,15 @@ const main = async () => {
 
   // -- Start testing stuff here --
 
+  /*
   const authorization = buildAuthorization({
-    userName: "WCopeland",
-    webApiKey: "gYPwmMOAIiGkOmk1qpNDrTfqBiGIeh7X"
-  });
+    userName: 'myUserName',
+    webApiKey: 'myWebApiKey'
+  })
 
-  const ticketData = await getTicketData(authorization, {});
-  console.log(ticketData);
+  const achievementCount = await getAchievementCount(authorization, 14_402);
+  console.log(achievementCount);
+  */
 };
 
 main();

package/src/user/getUserClaims.test.ts

@@ -0,0 +1,82 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserClaims } from "./getUserClaims";
+import type { GetUserClaimsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserClaims", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserClaims).toBeDefined();
+  });
+
+  it("given a username, retrieves a list of achievement set claims for the user", async () => {
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserClaimsResponse = [
+      {
+        ID: "1685",
+        User: "Jamiras",
+        GameID: "1492",
+        GameTitle: "Pinball Quest",
+        GameIcon: "/Images/011326.png",
+        ConsoleName: "NES",
+        ClaimType: "0",
+        SetType: "0",
+        Status: "1",
+        Extension: "0",
+        Special: "0",
+        Created: "2017-08-20 00:00:00",
+        DoneTime: "2017-08-20 00:00:00",
+        Updated: "2022-06-28 17:15:59",
+        MinutesLeft: "-2862348"
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserClaims.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserClaims(authorization, {
+      userName: "Jamiras"
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        id: 1685,
+        user: "Jamiras",
+        gameId: 1492,
+        gameTitle: "Pinball Quest",
+        gameIcon: "/Images/011326.png",
+        consoleName: "NES",
+        claimType: 0,
+        setType: 0,
+        status: 1,
+        extension: 0,
+        special: 0,
+        created: "2017-08-20 00:00:00",
+        doneTime: "2017-08-20 00:00:00",
+        updated: "2022-06-28 17:15:59",
+        minutesLeft: -2_862_348
+      }
+    ]);
+  });
+});

package/src/user/getUserClaims.ts

@@ -0,0 +1,59 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GetUserClaimsResponse, UserClaims } from "./models";
+
+/**
+ * A call to this function will retrieve a list of
+ * achievement set claims made over the lifetime of a given
+ * user, 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 historical
+ * achievement set claims list for.
+ *
+ * @example
+ * ```
+ * const userClaims = await getUserClaims(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing all the achievement set claims
+ * made over the lifetime of the given user.
+ */
+export const getUserClaims = async (
+  authorization: AuthObject,
+  payload: { userName: string }
+): Promise<UserClaims> => {
+  const { userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserClaims.php",
+    authorization,
+    { u: userName }
+  );
+
+  const rawResponse = await call<GetUserClaimsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "ID",
+      "GameID",
+      "ClaimType",
+      "SetType",
+      "Status",
+      "Extension",
+      "Special",
+      "MinutesLeft"
+    ]
+  });
+};

package/src/user/getUserCompletedGames.test.ts

@@ -0,0 +1,93 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserCompletedGames } from "./getUserCompletedGames";
+import type { GetUserCompletedGamesResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserCompletedGames", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserCompletedGames).toBeDefined();
+  });
+
+  it("given a username, returns completion metadata", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserCompletedGamesResponse = [
+      {
+        GameID: "1881",
+        Title: "Popeye",
+        ImageIcon: "/Images/065073.png",
+        ConsoleID: "7",
+        ConsoleName: "NES",
+        MaxPossible: "26",
+        NumAwarded: "12",
+        PctWon: "0.4615",
+        HardcoreMode: "0"
+      },
+      {
+        GameID: "1881",
+        Title: "Popeye",
+        ImageIcon: "/Images/065073.png",
+        ConsoleID: "7",
+        ConsoleName: "NES",
+        MaxPossible: "26",
+        NumAwarded: "12",
+        PctWon: "0.4615",
+        HardcoreMode: "1"
+      }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserCompletedGames.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserCompletedGames(authorization, {
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        gameId: 1881,
+        title: "Popeye",
+        imageIcon: "/Images/065073.png",
+        consoleId: 7,
+        consoleName: "NES",
+        maxPossible: 26,
+        numAwarded: 12,
+        pctWon: 0.4615,
+        hardcoreMode: false
+      },
+      {
+        gameId: 1881,
+        title: "Popeye",
+        imageIcon: "/Images/065073.png",
+        consoleId: 7,
+        consoleName: "NES",
+        maxPossible: 26,
+        numAwarded: 12,
+        pctWon: 0.4615,
+        hardcoreMode: true
+      }
+    ]);
+  });
+});

package/src/user/getUserCompletedGames.ts

@@ -0,0 +1,89 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserCompletedGamesResponse,
+  UserCompletedGames
+} from "./models";
+
+/**
+ * A call to this function will retrieve completion metadata
+ * 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.
+ *
+ * @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
+ * completion metadata for.
+ *
+ * @example
+ * ```
+ * const userCompletedGames = await getUserCompletedGames(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing completion metadata objects
+ * for a given user. Each game contains two completion records,
+ * one for softcore and another for hardcore.
+ * ```json
+ * [
+ *   {
+ *     gameId: 14976,
+ *     title: 'Mortal Kombat',
+ *     imageIcon: '/Images/036812.png',
+ *     consoleId: 27,
+ *     consoleName: 'Arcade',
+ *     maxPossible: 35,
+ *     numAwarded: 13,
+ *     pctWon: 0.3714,
+ *     hardcoreMode: false
+ *   },
+ *   {
+ *     gameId: 14976,
+ *     title: 'Mortal Kombat',
+ *     imageIcon: '/Images/036812.png',
+ *     consoleId: 27,
+ *     consoleName: 'Arcade',
+ *     maxPossible: 35,
+ *     numAwarded: 13,
+ *     pctWon: 0.3714,
+ *     hardcoreMode: true
+ *   },
+ * ]
+ * ```
+ */
+export const getUserCompletedGames = async (
+  authorization: AuthObject,
+  payload: { userName: string }
+): Promise<UserCompletedGames> => {
+  const { userName } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserCompletedGames.php",
+    authorization,
+    { u: userName }
+  );
+
+  const rawResponse = await call<GetUserCompletedGamesResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: [
+      "GameID",
+      "ConsoleID",
+      "MaxPossible",
+      "NumAwarded",
+      "PctWon"
+    ],
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};

package/src/user/getUserGameRankAndScore.ts

@@ -37,7 +37,7 @@ import type {
  * @returns An array containing metadata about the user's
  * rank and score for the target game ID. If metadata
  * cannot be found, the array is empty.
- * ```
+ * ```json
  * [
  *   {
  *     user: "xelnia",

package/src/user/index.ts

@@ -1,6 +1,8 @@
 export * from "./getAchievementsEarnedBetween";
 export * from "./getAchievementsEarnedOnDay";
 export * from "./getGameInfoAndUserProgress";
+export * from "./getUserClaims";
+export * from "./getUserCompletedGames";
 export * from "./getUserGameRankAndScore";
 export * from "./getUserPoints";
 export * from "./getUserProgress";

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

@@ -0,0 +1,13 @@
+interface UserCompletedGamesResponseEntity {
+  GameID: string;
+  Title: string;
+  ImageIcon: string;
+  ConsoleID: string;
+  ConsoleName: string;
+  MaxPossible: string;
+  NumAwarded: string;
+  PctWon: string;
+  HardcoreMode: "0" | "1";
+}
+
+export type GetUserCompletedGamesResponse = UserCompletedGamesResponseEntity[];

package/src/user/models/index.ts

@@ -2,11 +2,15 @@ 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-completed-games-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-claims.model";
+export * from "./user-claims-response.model";
+export * from "./user-completed-games.model";
 export * from "./user-game-rank-and-score.model";
 export * from "./user-points.model";
 export * from "./user-progress.model";

package/src/user/models/user-claims-response.model.ts

@@ -0,0 +1,19 @@
+interface UserClaimsResponseEntity {
+  ID: string;
+  User: string;
+  GameID: string;
+  GameTitle: string;
+  GameIcon: string;
+  ConsoleName: string;
+  ClaimType: string;
+  SetType: string;
+  Status: string;
+  Extension: string;
+  Special: string;
+  Created: string;
+  DoneTime: string;
+  Updated: string;
+  MinutesLeft: string;
+}
+
+export type GetUserClaimsResponse = UserClaimsResponseEntity[];

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

@@ -0,0 +1,19 @@
+interface UserClaim {
+  id: number;
+  user: string;
+  gameId: number;
+  gameTitle: string;
+  gameIcon: string;
+  consoleName: string;
+  claimType: number;
+  setType: number;
+  status: number;
+  extension: number;
+  special: number;
+  created: string;
+  doneTime: string;
+  updated: string;
+  minutesLeft: number;
+}
+
+export type UserClaims = UserClaim[];

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

@@ -0,0 +1,13 @@
+interface UserCompletedGame {
+  gameId: number;
+  title: string;
+  imageIcon: string;
+  consoleId: number;
+  consoleName: string;
+  maxPossible: number;
+  numAwarded: number;
+  pctWon: number;
+  hardcoreMode: boolean;
+}
+
+export type UserCompletedGames = UserCompletedGame[];