@retroachievements/api 2.2.0 → 2.4.0

package/dist/comment/getComments.d.ts

@@ -0,0 +1,58 @@
+import type { ID } from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { CommentsResponse } from "./models";
+/**
+ * A call to this function will retrieve a list of comments on a particular target.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.identifier The identifier to retrieve. For user walls, this will
+ * be a string (the username), and for game and achievement walls, this will be a
+ * the ID of the object in question.
+ *
+ * @param payload.kind What kind of identifier was used. This can be "game",
+ * "achievement", or "user".
+ *
+ * @param payload.offset Defaults to 0. The number of entries to skip.
+ *
+ * @param payload.count Defaults to 50, has a max of 500.
+ *
+ * @example
+ * ```
+ * // Retrieving game/achievement comments
+ * const gameWallComments = await getComments(
+ *   authorization,
+ *   { identifier: 20294, kind: 'game', count: 4, offset: 0 },
+ * );
+ *
+ * // Retrieving comments on a user's wall
+ * const userWallComments = await getComments(
+ *   authorization,
+ *   { identifier: "xelnia", count: 4, offset: 0 },
+ * );
+ * ```
+ *
+ * @returns An object containing the amount of comments retrieved,
+ * the total comments, and an array of the comments themselves.
+ * ```
+ * {
+ *   count: 4,
+ *   total: 4,
+ *   results: [
+ *   {
+ *     user: "PlayTester",
+ *     submitted: "2024-07-31T11:22:23.000000Z",
+ *     commentText: "Comment 1"
+ *   },
+ *   // ...
+ *   ]
+ * }
+ * ```
+ */
+export declare const getComments: (authorization: AuthObject, payload: {
+    identifier: ID;
+    kind?: "game" | "achievement" | "user";
+    offset?: number;
+    count?: number;
+}) => Promise<CommentsResponse>;

package/dist/comment/getComments.test.d.ts

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

package/dist/comment/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./getComments";
+export * from "./models";

package/dist/comment/models/comment-entity.model.d.ts

@@ -0,0 +1,6 @@
+export interface CommentEntity {
+    user: string;
+    submitted: string;
+    commentText: string;
+}
+export type Comment = CommentEntity;

package/dist/comment/models/comment-response.model.d.ts

@@ -0,0 +1,6 @@
+import type { CommentEntity } from "./comment-entity.model";
+export interface CommentsResponse {
+    count: number;
+    total: number;
+    results: CommentEntity[];
+}

package/dist/comment/models/get-comments-response.model.d.ts

@@ -0,0 +1,12 @@
+interface RawCommentsResponseEntity {
+    Count: number;
+    Total: number;
+    Results: RawComment[];
+}
+interface RawComment {
+    User: string;
+    Submitted: string;
+    CommentText: string;
+}
+export type GetCommentsResponse = RawCommentsResponseEntity;
+export {};

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

@@ -0,0 +1,3 @@
+export * from "./comment-entity.model";
+export * from "./comment-response.model";
+export * from "./get-comments-response.model";

package/dist/game/getGameHashes.d.ts

@@ -23,18 +23,18 @@ import type { GameHashes } from "./models";
  * @returns An object containing a list of game hashes.
  * ```json
  * {
- *   "Results": [
+ *   "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": "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
+ *       "md5": "1bc674be034e43c96b86487ac69d9293",
+ *       "name": "Sonic The Hedgehog (USA, Europe).md",
+ *       "labels": ["nointro"],
+ *       "patchUrl": null
  *     }
  *   ]
  * }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./achievement";
+export * from "./comment";
 export * from "./console";
 export * from "./feed";
 export * from "./game";

package/dist/user/getUserWantToPlayList.d.ts

@@ -0,0 +1,47 @@
+import type { AuthObject } from "../utils/public";
+import type { UserWantToPlayList } from "./models";
+/**
+ * A call to this function will retrieve a user's "Want to Play Games" list.
+ *
+ * @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
+ * want to play games list 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 wantToPlayList = await getUserWantToPlayList(
+ *   authorization,
+ *   { username: "wv_pinball" }
+ * );
+ * ```
+ *
+ * @returns An object containing a user's list of "Want to Play Games".
+ * ```json
+ * {
+ *   "count": 100,
+ *   "total": 1287,
+ *   "results": [
+ *     {
+ *       "id": 20246,
+ *       "title": "~Hack~ Knuckles the Echidna in Sonic the Hedgehog",
+ *       "imageIcon": "/Images/074560.png",
+ *       "consoleID": 1,
+ *       "consoleName": "Genesis/Mega Drive",
+ *       "pointsTotal": 1500,
+ *       "achievementsPublished": 50
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export declare const getUserWantToPlayList: (authorization: AuthObject, payload: {
+    username: string;
+    offset?: number;
+    count?: number;
+}) => Promise<UserWantToPlayList>;

package/dist/user/getUserWantToPlayList.test.d.ts

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

package/dist/user/index.d.ts

@@ -12,4 +12,5 @@ export * from "./getUserProgress";
 export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";
 export * from "./getUserSummary";
+export * from "./getUserWantToPlayList";
 export * from "./models";

package/dist/user/models/get-user-want-to-play-list-response.model.d.ts

@@ -0,0 +1,13 @@
+export interface GetUserWantToPlayListResponse {
+    Count: number;
+    Total: number;
+    Results: Array<{
+        ID: number;
+        Title: string;
+        ImageIcon: string;
+        ConsoleID: number;
+        ConsoleName: string;
+        PointsTotal: number;
+        AchievementsPublished: number;
+    }>;
+}

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

@@ -13,6 +13,7 @@ export * from "./get-user-progress-response.model";
 export * from "./get-user-recent-achievements-response.model";
 export * from "./get-user-recently-played-games-response.model";
 export * from "./get-user-summary-response.model";
+export * from "./get-user-want-to-play-list-response.model";
 export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
@@ -26,3 +27,4 @@ export * from "./user-progress.model";
 export * from "./user-recent-achievement.model";
 export * from "./user-recently-played-games.model";
 export * from "./user-summary.model";
+export * from "./user-want-to-play-list.model";

package/dist/user/models/user-want-to-play-list.model.d.ts

@@ -0,0 +1,13 @@
+export interface UserWantToPlayList {
+    count: number;
+    total: number;
+    results: Array<{
+        id: number;
+        title: string;
+        imageIcon: string;
+        consoleId: number;
+        consoleName: string;
+        pointsTotal: number;
+        achievementsPublished: number;
+    }>;
+}

package/package.json

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

package/src/comment/getComments.test.ts

@@ -0,0 +1,277 @@
+/* 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 { getComments } from "./getComments";
+import type { CommentsResponse, GetCommentsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getComments", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getComments).toBeDefined();
+  });
+
+  it("retrieves the comments on a user's wall", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetCommentsResponse = {
+      Count: 2,
+      Total: 2,
+      Results: [
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 1",
+        },
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 2",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetComments.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getComments(authorization, {
+      identifier: "xelnia",
+    });
+
+    // ASSERT
+    const expectedResponse: CommentsResponse = {
+      count: 2,
+      total: 2,
+      results: [
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 1",
+        },
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 2",
+        },
+      ],
+    };
+
+    expect(response).toEqual(expectedResponse);
+  });
+
+  it("retrieves the comments on an game", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetCommentsResponse = {
+      Count: 2,
+      Total: 2,
+      Results: [
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 1",
+        },
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 2",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetComments.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getComments(authorization, {
+      identifier: 321_865,
+      kind: "game",
+    });
+
+    // ASSERT
+    const expectedResponse: CommentsResponse = {
+      count: 2,
+      total: 2,
+      results: [
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 1",
+        },
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 2",
+        },
+      ],
+    };
+
+    expect(response).toEqual(expectedResponse);
+  });
+
+  it("retrieves the comments on an achievement, respecting count", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetCommentsResponse = {
+      Count: 2,
+      Total: 4,
+      Results: [
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 1",
+        },
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 2",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetComments.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getComments(authorization, {
+      identifier: 321_865,
+      count: 2,
+      kind: "achievement",
+    });
+
+    // ASSERT
+    const expectedResponse: CommentsResponse = {
+      count: 2,
+      total: 4,
+      results: [
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 1",
+        },
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 2",
+        },
+      ],
+    };
+
+    expect(response).toEqual(expectedResponse);
+  });
+
+  it("retrieves the comments on an game, respecting offset", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetCommentsResponse = {
+      Count: 1,
+      Total: 2,
+      Results: [
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 2",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetComments.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getComments(authorization, {
+      identifier: 321_865,
+      offset: 1,
+      kind: "game",
+    });
+
+    // ASSERT
+    const expectedResponse: CommentsResponse = {
+      count: 1,
+      total: 2,
+      results: [
+        {
+          user: "PlayTester",
+          submitted: "2024-07-31T11:22:23.000000Z",
+          commentText: "Comment 2",
+        },
+      ],
+    };
+
+    expect(response).toEqual(expectedResponse);
+  });
+
+  it("warns the developer when they don't specify kind for achievements/games", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetCommentsResponse = {
+      Count: 1,
+      Total: 2,
+      Results: [
+        {
+          User: "PlayTester",
+          Submitted: "2024-07-31T11:22:23.000000Z",
+          CommentText: "Comment 2",
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetComments.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = getComments(authorization, {
+      identifier: 321_865,
+      offset: 1,
+    });
+
+    // ASSERT
+    await expect(response).rejects.toThrow(TypeError);
+  });
+});

package/src/comment/getComments.ts

@@ -0,0 +1,107 @@
+import type { ID } from "../utils/internal";
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties,
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { CommentsResponse, GetCommentsResponse } from "./models";
+
+const kindMap: Record<"game" | "achievement" | "user", number> = {
+  game: 1,
+  achievement: 2,
+  user: 3,
+};
+
+/**
+ * A call to this function will retrieve a list of comments on a particular target.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.identifier The identifier to retrieve. For user walls, this will
+ * be a string (the username), and for game and achievement walls, this will be a
+ * the ID of the object in question.
+ *
+ * @param payload.kind What kind of identifier was used. This can be "game",
+ * "achievement", or "user".
+ *
+ * @param payload.offset Defaults to 0. The number of entries to skip.
+ *
+ * @param payload.count Defaults to 50, has a max of 500.
+ *
+ * @example
+ * ```
+ * // Retrieving game/achievement comments
+ * const gameWallComments = await getComments(
+ *   authorization,
+ *   { identifier: 20294, kind: 'game', count: 4, offset: 0 },
+ * );
+ *
+ * // Retrieving comments on a user's wall
+ * const userWallComments = await getComments(
+ *   authorization,
+ *   { identifier: "xelnia", count: 4, offset: 0 },
+ * );
+ * ```
+ *
+ * @returns An object containing the amount of comments retrieved,
+ * the total comments, and an array of the comments themselves.
+ * ```
+ * {
+ *   count: 4,
+ *   total: 4,
+ *   results: [
+ *   {
+ *     user: "PlayTester",
+ *     submitted: "2024-07-31T11:22:23.000000Z",
+ *     commentText: "Comment 1"
+ *   },
+ *   // ...
+ *   ]
+ * }
+ * ```
+ */
+export const getComments = async (
+  authorization: AuthObject,
+  payload: {
+    identifier: ID;
+    kind?: "game" | "achievement" | "user";
+    offset?: number;
+    count?: number;
+  }
+): Promise<CommentsResponse> => {
+  const { identifier, kind, offset, count } = payload;
+
+  const queryParams: Record<string, number | string> = { i: identifier };
+
+  if (kind) {
+    queryParams.t = kindMap[kind];
+  } else if (typeof identifier === "number") {
+    throw new TypeError(
+      "'kind' must be specified when looking up an achievement or game."
+    );
+  }
+
+  if (offset) {
+    queryParams.o = offset;
+  }
+
+  if (count) {
+    queryParams.c = count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetComments.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetCommentsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["Count", "Total"],
+  });
+};

package/src/comment/index.ts

@@ -0,0 +1,2 @@
+export * from "./getComments";
+export * from "./models";

package/src/comment/models/comment-entity.model.ts

@@ -0,0 +1,7 @@
+export interface CommentEntity {
+  user: string;
+  submitted: string;
+  commentText: string;
+}
+
+export type Comment = CommentEntity;

package/src/comment/models/comment-response.model.ts

@@ -0,0 +1,7 @@
+import type { CommentEntity } from "./comment-entity.model";
+
+export interface CommentsResponse {
+  count: number;
+  total: number;
+  results: CommentEntity[];
+}

package/src/comment/models/get-comments-response.model.ts

@@ -0,0 +1,13 @@
+interface RawCommentsResponseEntity {
+  Count: number;
+  Total: number;
+  Results: RawComment[];
+}
+
+interface RawComment {
+  User: string;
+  Submitted: string;
+  CommentText: string;
+}
+
+export type GetCommentsResponse = RawCommentsResponseEntity;

package/src/comment/models/index.ts

@@ -0,0 +1,3 @@
+export * from "./comment-entity.model";
+export * from "./comment-response.model";
+export * from "./get-comments-response.model";

package/src/game/getGameExtended.test.ts

@@ -75,7 +75,10 @@ describe("Function: getGameExtended", () => {
     );
 
     // ACT
-    const response = await getGameExtended(authorization, { gameId: 14_402 });
+    const response = await getGameExtended(authorization, {
+      gameId: 14_402,
+      isRequestingUnofficialAchievements: true,
+    });
 
     // ASSERT
     expect(response).toEqual({