feat: add parameter for 'kind', and test for it missing when needed

Author: bramdelta

src/comments/getComments.test.ts

@@ -77,7 +77,7 @@ describe("Function: getComments", () => {
     expect(response).toEqual(expectedResponse);
   });
 
-  it("retrieves the comments on an game or achievement", async () => {
+  it("retrieves the comments on an game", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
       username: "mockUserName",
@@ -110,6 +110,7 @@ describe("Function: getComments", () => {
     // ACT
     const response = await getComments(authorization, {
       identifier: 321_865,
+      kind: 1,
     });
 
     // ASSERT
@@ -133,7 +134,7 @@ describe("Function: getComments", () => {
     expect(response).toEqual(expectedResponse);
   });
 
-  it("retrieves the comments on an game or achievement, respecting count", async () => {
+  it("retrieves the comments on an achievement, respecting count", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
       username: "mockUserName",
@@ -167,6 +168,7 @@ describe("Function: getComments", () => {
     const response = await getComments(authorization, {
       identifier: 321_865,
       count: 2,
+      kind: 2,
     });
 
     // ASSERT
@@ -190,7 +192,7 @@ describe("Function: getComments", () => {
     expect(response).toEqual(expectedResponse);
   });
 
-  it("retrieves the comments on an game or achievement, respecting offset", async () => {
+  it("retrieves the comments on an game, respecting offset", async () => {
     // ARRANGE
     const authorization = buildAuthorization({
       username: "mockUserName",
@@ -219,6 +221,7 @@ describe("Function: getComments", () => {
     const response = await getComments(authorization, {
       identifier: 321_865,
       offset: 1,
+      kind: 1,
     });
 
     // ASSERT
@@ -236,4 +239,39 @@ describe("Function: getComments", () => {
 
     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);
+  });
 });

src/comments/getComments.ts

@@ -18,6 +18,9 @@ import type { Comments, GetCommentsResponse } from "./models";
  * 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 corresponds to 1 for a game,
+ * 2 for an achievement, and 3 for a user. Required if type is 1 or 2.
+ *
  * @param payload.offset Defaults to 0. The number of entries to skip.
  *
  * @param payload.count Defaults to 50, has a max of 500.
@@ -56,11 +59,19 @@ import type { Comments, GetCommentsResponse } from "./models";
  */
 export const getComments = async (
   authorization: AuthObject,
-  payload: { identifier: ID | string; offset?: number; count?: number }
+  payload: { identifier: ID; kind?: number; offset?: number; count?: number }
 ): Promise<Comments> => {
-  const { identifier, offset, count } = payload;
+  const { identifier, kind, offset, count } = payload;
+
+  const queryParams: Record<string, number | string> = { i: identifier };
 
-  const queryParams: Record<string, number | string> = { i: identifier, t: 1 };
+  if (kind) {
+    queryParams.t = 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;