From 99a5b21227d08d006be09dbc60a1002e9adfbf0b Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 15:01:46 -0400 Subject: [PATCH 01/18] WIP: Add comments module and code for getCommentsOnUserWall --- src/comments/getCommentsOnAchievementWall.ts | 0 src/comments/getCommentsOnGameWall.ts | 0 src/comments/getCommentsOnUserWall.ts | 56 +++++++++++++++++++ src/comments/index.ts | 3 + src/comments/models/comment-response.model.ts | 13 +++++ src/comments/models/index.ts | 1 + src/index.ts | 1 + 7 files changed, 74 insertions(+) create mode 100644 src/comments/getCommentsOnAchievementWall.ts create mode 100644 src/comments/getCommentsOnGameWall.ts create mode 100644 src/comments/getCommentsOnUserWall.ts create mode 100644 src/comments/index.ts create mode 100644 src/comments/models/comment-response.model.ts create mode 100644 src/comments/models/index.ts diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts new file mode 100644 index 0000000..e69de29 diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts new file mode 100644 index 0000000..e69de29 diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts new file mode 100644 index 0000000..5045f5c --- /dev/null +++ b/src/comments/getCommentsOnUserWall.ts @@ -0,0 +1,56 @@ +import { + apiBaseUrl, + buildRequestUrl, + call, + serializeProperties, +} from "../utils/internal"; +import type { AuthObject } from "../utils/public"; + +import { GetComments } from "./models"; + +/** + * A call to this function will retrieve a list of + * comments on a identifier. This can be a gameId, userId, or achievementId + * + * @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 + * comments of (their wall). + * + * @param payload.identifier The ID or username of the object in question. + * + * @param payload.type What type of object you're requesting. Needed if you + * are requesting a game (1) or achievement (2), since the IDs may overlap. + * + * @example + * ``` + * const comments = await getComments( + * authorization, + * { username: "Jamiras" }, + * ); + * ``` + * + * @returns An array containing all the achievement set claims + * made over the lifetime of the given user. + */ + +export const getCommentsOnUserWall = async ( + authorization: AuthObject, + payload: { username: string }, +): Promise => { + const { username } = payload; + + const url = buildRequestUrl( + apiBaseUrl, + "/API_GetComments.php", + authorization, + { i: username }, + ); + + const rawResponse = await call({ url }); + + return serializeProperties(rawResponse, { + shouldCastToNumbers: ["Count", "Total"], + }); +}; diff --git a/src/comments/index.ts b/src/comments/index.ts new file mode 100644 index 0000000..df9c90d --- /dev/null +++ b/src/comments/index.ts @@ -0,0 +1,3 @@ +// export * from "./getCommentsOnGameWall"; +export * from "./getCommentsOnUserWall"; +// export * from "./getCommentsOnAchievementWall"; diff --git a/src/comments/models/comment-response.model.ts b/src/comments/models/comment-response.model.ts new file mode 100644 index 0000000..2bd208f --- /dev/null +++ b/src/comments/models/comment-response.model.ts @@ -0,0 +1,13 @@ +interface CommentsResponseEntity { + Count: number; + Total: number; + Results: CommentEntity[]; +} + +interface CommentEntity { + User: string; + Submitted: string; + CommentText: string; +} +export type GetComments = CommentsResponseEntity; +// export type CommentEntity = CommentEntity; diff --git a/src/comments/models/index.ts b/src/comments/models/index.ts new file mode 100644 index 0000000..b15b2ac --- /dev/null +++ b/src/comments/models/index.ts @@ -0,0 +1 @@ +export * from "./comment-response.model"; diff --git a/src/index.ts b/src/index.ts index 15334be..8e0352e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,6 +2,7 @@ export * from "./achievement"; export * from "./console"; +export * from "./comments"; export * from "./feed"; export * from "./game"; export * from "./ticket"; From 3f4ba9f1b77cc41bcb6744f140281be46a6d6527 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 15:30:47 -0400 Subject: [PATCH 02/18] fix: properly export types and modules --- src/comments/getCommentsOnAchievementWall.ts | 0 src/comments/getCommentsOnGameWall.ts | 0 src/comments/getCommentsOnUserWall.ts | 7 +++---- src/comments/index.ts | 1 + src/comments/models/comment-response.model.ts | 1 - src/comments/models/comment.model.ts | 5 +++++ src/comments/models/index.ts | 1 + src/index.ts | 2 +- 8 files changed, 11 insertions(+), 6 deletions(-) delete mode 100644 src/comments/getCommentsOnAchievementWall.ts delete mode 100644 src/comments/getCommentsOnGameWall.ts create mode 100644 src/comments/models/comment.model.ts diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts deleted file mode 100644 index e69de29..0000000 diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts deleted file mode 100644 index e69de29..0000000 diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts index 5045f5c..6670102 100644 --- a/src/comments/getCommentsOnUserWall.ts +++ b/src/comments/getCommentsOnUserWall.ts @@ -5,8 +5,7 @@ import { serializeProperties, } from "../utils/internal"; import type { AuthObject } from "../utils/public"; - -import { GetComments } from "./models"; +import type { GetComments } from "./models"; /** * A call to this function will retrieve a list of @@ -37,7 +36,7 @@ import { GetComments } from "./models"; export const getCommentsOnUserWall = async ( authorization: AuthObject, - payload: { username: string }, + payload: { username: string } ): Promise => { const { username } = payload; @@ -45,7 +44,7 @@ export const getCommentsOnUserWall = async ( apiBaseUrl, "/API_GetComments.php", authorization, - { i: username }, + { i: username } ); const rawResponse = await call({ url }); diff --git a/src/comments/index.ts b/src/comments/index.ts index df9c90d..42bcdd1 100644 --- a/src/comments/index.ts +++ b/src/comments/index.ts @@ -1,3 +1,4 @@ // export * from "./getCommentsOnGameWall"; export * from "./getCommentsOnUserWall"; // export * from "./getCommentsOnAchievementWall"; +export * from "./models"; diff --git a/src/comments/models/comment-response.model.ts b/src/comments/models/comment-response.model.ts index 2bd208f..fb81117 100644 --- a/src/comments/models/comment-response.model.ts +++ b/src/comments/models/comment-response.model.ts @@ -10,4 +10,3 @@ interface CommentEntity { CommentText: string; } export type GetComments = CommentsResponseEntity; -// export type CommentEntity = CommentEntity; diff --git a/src/comments/models/comment.model.ts b/src/comments/models/comment.model.ts new file mode 100644 index 0000000..e45d9db --- /dev/null +++ b/src/comments/models/comment.model.ts @@ -0,0 +1,5 @@ +export interface Comment { + User: string; + Submitted: string; + CommentText: string; +} diff --git a/src/comments/models/index.ts b/src/comments/models/index.ts index b15b2ac..312cdde 100644 --- a/src/comments/models/index.ts +++ b/src/comments/models/index.ts @@ -1 +1,2 @@ +export * from "./comment.model"; export * from "./comment-response.model"; diff --git a/src/index.ts b/src/index.ts index 8e0352e..8ded3a1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,8 +1,8 @@ // This file is the single public-facing API of the entire library. export * from "./achievement"; -export * from "./console"; export * from "./comments"; +export * from "./console"; export * from "./feed"; export * from "./game"; export * from "./ticket"; From 20130b40e4f088f184f6b82b2743ec9b4f30fd10 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 16:22:30 -0400 Subject: [PATCH 03/18] refactor: use camelcase for comment api --- src/comments/models/comment-response.model.ts | 13 +++++-------- src/comments/models/comment.model.ts | 6 +++--- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/src/comments/models/comment-response.model.ts b/src/comments/models/comment-response.model.ts index fb81117..ea99064 100644 --- a/src/comments/models/comment-response.model.ts +++ b/src/comments/models/comment-response.model.ts @@ -1,12 +1,9 @@ +import type { Comment } from "./comment.model"; + interface CommentsResponseEntity { - Count: number; - Total: number; - Results: CommentEntity[]; + count: number; + total: number; + results: Comment[]; } -interface CommentEntity { - User: string; - Submitted: string; - CommentText: string; -} export type GetComments = CommentsResponseEntity; diff --git a/src/comments/models/comment.model.ts b/src/comments/models/comment.model.ts index e45d9db..ba004d3 100644 --- a/src/comments/models/comment.model.ts +++ b/src/comments/models/comment.model.ts @@ -1,5 +1,5 @@ export interface Comment { - User: string; - Submitted: string; - CommentText: string; + user: string; + submitted: string; + commentText: string; } From 042abef65092680d79ba490cb6e512a4de51f076 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 16:38:50 -0400 Subject: [PATCH 04/18] feat: add api routes for getting comments on games and achievements --- src/comments/getCommentsOnAchievementWall.ts | 47 ++++++++++++++++++++ src/comments/getCommentsOnGameWall.ts | 47 ++++++++++++++++++++ src/comments/getCommentsOnUserWall.ts | 18 +++----- src/comments/index.ts | 4 +- 4 files changed, 101 insertions(+), 15 deletions(-) create mode 100644 src/comments/getCommentsOnAchievementWall.ts create mode 100644 src/comments/getCommentsOnGameWall.ts diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts new file mode 100644 index 0000000..46d1e53 --- /dev/null +++ b/src/comments/getCommentsOnAchievementWall.ts @@ -0,0 +1,47 @@ +import { + apiBaseUrl, + buildRequestUrl, + call, + serializeProperties, +} from "../utils/internal"; +import type { AuthObject } from "../utils/public"; +import type { GetComments } from "./models"; + +/** + * A call to this function will retrieve a list of comments on a achievement. + * + * @param authorization An object containing your username and webApiKey. + * This can be constructed with `buildAuthorization()`. + * + * @param payload.achievementId The achievementId ID to get the comments for. + * + * @example + * ``` + * const achievementComments = await getCommentsOnAchievementWall( + * authorization, + * { achievementId: 321865 }, + * ); + * ``` + * + * @returns An array containing all the comments on the given achievement. + */ + +export const getCommentsOnAchievementWall = async ( + authorization: AuthObject, + payload: { achievementId: string } +): Promise => { + const { achievementId } = payload; + + const url = buildRequestUrl( + apiBaseUrl, + "/API_GetComments.php", + authorization, + { i: achievementId, t: 2 } + ); + + const rawResponse = await call({ url }); + + return serializeProperties(rawResponse, { + shouldCastToNumbers: ["Count", "Total"], + }); +}; diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts new file mode 100644 index 0000000..1213024 --- /dev/null +++ b/src/comments/getCommentsOnGameWall.ts @@ -0,0 +1,47 @@ +import { + apiBaseUrl, + buildRequestUrl, + call, + serializeProperties, +} from "../utils/internal"; +import type { AuthObject } from "../utils/public"; +import type { GetComments } from "./models"; + +/** + * A call to this function will retrieve a list of comments on a game's page. + * + * @param authorization An object containing your username and webApiKey. + * This can be constructed with `buildAuthorization()`. + * + * @param payload.gameId The gameId ID to get the comments for. + * + * @example + * ``` + * const userWallComments = await getCommentsOnUserWall( + * authorization, + * { gameId: 20294 }, + * ); + * ``` + * + * @returns An array containing all the comments on the game's page. + */ + +export const getCommentsOnGameWall = async ( + authorization: AuthObject, + payload: { gameId: number } +): Promise => { + const { gameId } = payload; + + const url = buildRequestUrl( + apiBaseUrl, + "/API_GetComments.php", + authorization, + { i: gameId, t: 1 } + ); + + const rawResponse = await call({ url }); + + return serializeProperties(rawResponse, { + shouldCastToNumbers: ["Count", "Total"], + }); +}; diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts index 6670102..16369da 100644 --- a/src/comments/getCommentsOnUserWall.ts +++ b/src/comments/getCommentsOnUserWall.ts @@ -8,30 +8,22 @@ import type { AuthObject } from "../utils/public"; import type { GetComments } from "./models"; /** - * A call to this function will retrieve a list of - * comments on a identifier. This can be a gameId, userId, or achievementId + * A call to this function will retrieve a list of comments on a user's wall. * * @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 - * comments of (their wall). - * - * @param payload.identifier The ID or username of the object in question. - * - * @param payload.type What type of object you're requesting. Needed if you - * are requesting a game (1) or achievement (2), since the IDs may overlap. + * @param payload.username The username to get the comments wall for. * * @example * ``` - * const comments = await getComments( + * const userWallComments = await getCommentsOnUserWall( * authorization, - * { username: "Jamiras" }, + * { username: "xelnia" }, * ); * ``` * - * @returns An array containing all the achievement set claims - * made over the lifetime of the given user. + * @returns An array containing all the comments on the user's wall. */ export const getCommentsOnUserWall = async ( diff --git a/src/comments/index.ts b/src/comments/index.ts index 42bcdd1..70d9dfb 100644 --- a/src/comments/index.ts +++ b/src/comments/index.ts @@ -1,4 +1,4 @@ -// export * from "./getCommentsOnGameWall"; +export * from "./getCommentsOnAchievementWall"; +export * from "./getCommentsOnGameWall"; export * from "./getCommentsOnUserWall"; -// export * from "./getCommentsOnAchievementWall"; export * from "./models"; From e6aa9c7a3cf1ba0d2dd6a6abfdfcee419d1b5553 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 17:21:27 -0400 Subject: [PATCH 05/18] fix: allow offset and count in comment retrieval --- src/comments/getCommentsOnAchievementWall.ts | 46 +++++++++++++++++--- src/comments/getCommentsOnGameWall.ts | 43 +++++++++++++++--- src/comments/getCommentsOnUserWall.ts | 36 ++++++++++++--- 3 files changed, 105 insertions(+), 20 deletions(-) diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts index 46d1e53..6df70a3 100644 --- a/src/comments/getCommentsOnAchievementWall.ts +++ b/src/comments/getCommentsOnAchievementWall.ts @@ -1,3 +1,4 @@ +import type { ID } from "../utils/internal"; import { apiBaseUrl, buildRequestUrl, @@ -13,30 +14,61 @@ import type { GetComments } from "./models"; * @param authorization An object containing your username and webApiKey. * This can be constructed with `buildAuthorization()`. * - * @param payload.achievementId The achievementId ID to get the comments for. + * @param payload.achievementId The achievement ID to get the comments for. + * + * @param payload.offset Defaults to 0. The number of entries to skip. + * + * @param payload.count Defaults to 50, has a max of 500. * * @example * ``` * const achievementComments = await getCommentsOnAchievementWall( * authorization, - * { achievementId: 321865 }, + * { achievementId: 321865, count: 4, offset: 0 }, * ); * ``` * - * @returns An array containing all the comments on the given achievement. + * @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 getCommentsOnAchievementWall = async ( authorization: AuthObject, - payload: { achievementId: string } + payload: { achievementId: ID; offset?: number; count?: number } ): Promise => { - const { achievementId } = payload; + const { achievementId, offset, count } = payload; + + const queryParams: Record = { + i: achievementId, + t: 2, + }; + + if (offset) { + queryParams.o = offset; + } + + if (count) { + queryParams.c = count; + } const url = buildRequestUrl( apiBaseUrl, "/API_GetComments.php", authorization, - { i: achievementId, t: 2 } + queryParams ); const rawResponse = await call({ url }); diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts index 1213024..489f633 100644 --- a/src/comments/getCommentsOnGameWall.ts +++ b/src/comments/getCommentsOnGameWall.ts @@ -1,3 +1,4 @@ +import type { ID } from "../utils/internal"; import { apiBaseUrl, buildRequestUrl, @@ -15,28 +16,56 @@ import type { GetComments } from "./models"; * * @param payload.gameId The gameId ID to get the comments for. * + * @param payload.offset Defaults to 0. The number of entries to skip. + * + * @param payload.count Defaults to 50, has a max of 500. + * * @example * ``` - * const userWallComments = await getCommentsOnUserWall( + * const gameWallComments = await getCommentsOnGameWall( * authorization, - * { gameId: 20294 }, + * { gameId: 20294, count: 4, offset: 0 }, * ); * ``` * - * @returns An array containing all the comments on the game's page. + * @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 getCommentsOnGameWall = async ( authorization: AuthObject, - payload: { gameId: number } + payload: { gameId: ID; offset?: number; count?: number } ): Promise => { - const { gameId } = payload; + const { gameId, offset, count } = payload; + + const queryParams: Record = { i: gameId, t: 1 }; + + if (offset) { + queryParams.o = offset; + } + + if (count) { + queryParams.c = count; + } const url = buildRequestUrl( apiBaseUrl, "/API_GetComments.php", authorization, - { i: gameId, t: 1 } + queryParams ); const rawResponse = await call({ url }); diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts index 16369da..1d687a7 100644 --- a/src/comments/getCommentsOnUserWall.ts +++ b/src/comments/getCommentsOnUserWall.ts @@ -19,24 +19,48 @@ import type { GetComments } from "./models"; * ``` * const userWallComments = await getCommentsOnUserWall( * authorization, - * { username: "xelnia" }, + * { username: "xelnia", count: 4, offset: 0 }, * ); * ``` * - * @returns An array containing all the comments on the user's wall. + * @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 getCommentsOnUserWall = async ( authorization: AuthObject, - payload: { username: string } + payload: { username: string; offset?: number; count?: number } ): Promise => { - const { username } = payload; + const { username, offset, count } = payload; + + const queryParams: Record = { i: username }; + + if (offset) { + queryParams.o = offset; + } + + if (count) { + queryParams.c = count; + } const url = buildRequestUrl( apiBaseUrl, "/API_GetComments.php", authorization, - { i: username } + queryParams ); const rawResponse = await call({ url }); From c7891fb508d6b0388ac7dbe003c764150988f2cb Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 17:41:48 -0400 Subject: [PATCH 06/18] refactor: use proper response model for types --- src/comments/getCommentsOnAchievementWall.ts | 6 +++--- src/comments/getCommentsOnGameWall.ts | 6 +++--- src/comments/getCommentsOnUserWall.ts | 6 +++--- src/comments/models/comment-response.model.ts | 9 --------- src/comments/models/comment.model.ts | 5 ----- src/comments/models/comments.model.ts | 14 ++++++++++++++ src/comments/models/get-comments-response.ts | 13 +++++++++++++ src/comments/models/index.ts | 4 ++-- 8 files changed, 38 insertions(+), 25 deletions(-) delete mode 100644 src/comments/models/comment-response.model.ts delete mode 100644 src/comments/models/comment.model.ts create mode 100644 src/comments/models/comments.model.ts create mode 100644 src/comments/models/get-comments-response.ts diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts index 6df70a3..6d883ac 100644 --- a/src/comments/getCommentsOnAchievementWall.ts +++ b/src/comments/getCommentsOnAchievementWall.ts @@ -6,7 +6,7 @@ import { serializeProperties, } from "../utils/internal"; import type { AuthObject } from "../utils/public"; -import type { GetComments } from "./models"; +import type { Comments, GetCommentsResponse } from "./models"; /** * A call to this function will retrieve a list of comments on a achievement. @@ -48,7 +48,7 @@ import type { GetComments } from "./models"; export const getCommentsOnAchievementWall = async ( authorization: AuthObject, payload: { achievementId: ID; offset?: number; count?: number } -): Promise => { +): Promise => { const { achievementId, offset, count } = payload; const queryParams: Record = { @@ -71,7 +71,7 @@ export const getCommentsOnAchievementWall = async ( queryParams ); - const rawResponse = await call({ url }); + const rawResponse = await call({ url }); return serializeProperties(rawResponse, { shouldCastToNumbers: ["Count", "Total"], diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts index 489f633..9c48e4a 100644 --- a/src/comments/getCommentsOnGameWall.ts +++ b/src/comments/getCommentsOnGameWall.ts @@ -6,7 +6,7 @@ import { serializeProperties, } from "../utils/internal"; import type { AuthObject } from "../utils/public"; -import type { GetComments } from "./models"; +import type { Comments, GetCommentsResponse } from "./models"; /** * A call to this function will retrieve a list of comments on a game's page. @@ -48,7 +48,7 @@ import type { GetComments } from "./models"; export const getCommentsOnGameWall = async ( authorization: AuthObject, payload: { gameId: ID; offset?: number; count?: number } -): Promise => { +): Promise => { const { gameId, offset, count } = payload; const queryParams: Record = { i: gameId, t: 1 }; @@ -68,7 +68,7 @@ export const getCommentsOnGameWall = async ( queryParams ); - const rawResponse = await call({ url }); + const rawResponse = await call({ url }); return serializeProperties(rawResponse, { shouldCastToNumbers: ["Count", "Total"], diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts index 1d687a7..befe18b 100644 --- a/src/comments/getCommentsOnUserWall.ts +++ b/src/comments/getCommentsOnUserWall.ts @@ -5,7 +5,7 @@ import { serializeProperties, } from "../utils/internal"; import type { AuthObject } from "../utils/public"; -import type { GetComments } from "./models"; +import type { Comments, GetCommentsResponse } from "./models"; /** * A call to this function will retrieve a list of comments on a user's wall. @@ -43,7 +43,7 @@ import type { GetComments } from "./models"; export const getCommentsOnUserWall = async ( authorization: AuthObject, payload: { username: string; offset?: number; count?: number } -): Promise => { +): Promise => { const { username, offset, count } = payload; const queryParams: Record = { i: username }; @@ -63,7 +63,7 @@ export const getCommentsOnUserWall = async ( queryParams ); - const rawResponse = await call({ url }); + const rawResponse = await call({ url }); return serializeProperties(rawResponse, { shouldCastToNumbers: ["Count", "Total"], diff --git a/src/comments/models/comment-response.model.ts b/src/comments/models/comment-response.model.ts deleted file mode 100644 index ea99064..0000000 --- a/src/comments/models/comment-response.model.ts +++ /dev/null @@ -1,9 +0,0 @@ -import type { Comment } from "./comment.model"; - -interface CommentsResponseEntity { - count: number; - total: number; - results: Comment[]; -} - -export type GetComments = CommentsResponseEntity; diff --git a/src/comments/models/comment.model.ts b/src/comments/models/comment.model.ts deleted file mode 100644 index ba004d3..0000000 --- a/src/comments/models/comment.model.ts +++ /dev/null @@ -1,5 +0,0 @@ -export interface Comment { - user: string; - submitted: string; - commentText: string; -} diff --git a/src/comments/models/comments.model.ts b/src/comments/models/comments.model.ts new file mode 100644 index 0000000..6ffe081 --- /dev/null +++ b/src/comments/models/comments.model.ts @@ -0,0 +1,14 @@ +interface CommentEntity { + user: string; + submitted: string; + commentText: string; +} + +interface CommentsEntity { + count: number; + total: number; + results: CommentEntity[]; +} + +export type Comments = CommentsEntity; +export type Comment = CommentEntity; diff --git a/src/comments/models/get-comments-response.ts b/src/comments/models/get-comments-response.ts new file mode 100644 index 0000000..0d3dd25 --- /dev/null +++ b/src/comments/models/get-comments-response.ts @@ -0,0 +1,13 @@ +interface RawComment { + User: string; + Submitted: string; + CommentText: string; +} + +interface RawCommentsResponseEntity { + Count: number; + Total: number; + Results: RawComment[]; +} + +export type GetCommentsResponse = RawCommentsResponseEntity; diff --git a/src/comments/models/index.ts b/src/comments/models/index.ts index 312cdde..fb4394f 100644 --- a/src/comments/models/index.ts +++ b/src/comments/models/index.ts @@ -1,2 +1,2 @@ -export * from "./comment.model"; -export * from "./comment-response.model"; +export * from "./comments.model"; +export * from "./get-comments-response"; From 95209d408c98d73d2e80604356a5e2f324c19e66 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 17:53:38 -0400 Subject: [PATCH 07/18] test: add tests for comment retrieval functions --- .../getCommentsOnAchievementWall.test.ts | 81 +++++++++++++++++++ src/comments/getCommentsOnGameWall.test.ts | 81 +++++++++++++++++++ src/comments/getCommentsOnUserWall.test.ts | 81 +++++++++++++++++++ 3 files changed, 243 insertions(+) create mode 100644 src/comments/getCommentsOnAchievementWall.test.ts create mode 100644 src/comments/getCommentsOnGameWall.test.ts create mode 100644 src/comments/getCommentsOnUserWall.test.ts diff --git a/src/comments/getCommentsOnAchievementWall.test.ts b/src/comments/getCommentsOnAchievementWall.test.ts new file mode 100644 index 0000000..508ad2a --- /dev/null +++ b/src/comments/getCommentsOnAchievementWall.test.ts @@ -0,0 +1,81 @@ +/* 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 { getCommentsOnAchievementWall } from "./getCommentsOnAchievementWall"; +import type { Comments, GetCommentsResponse } from "./models"; + +const server = setupServer(); + +describe("Function: getCommentsOnAchievementWall", () => { + // MSW Setup + beforeAll(() => server.listen()); + afterEach(() => server.resetHandlers()); + afterAll(() => server.close()); + + it("is defined #sanity", () => { + // ASSERT + expect(getCommentsOnAchievementWall).toBeDefined(); + }); + + it("retrieves the comments on an achievement and cleans properties", 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 getCommentsOnAchievementWall(authorization, { + achievementId: 321_865, + count: 2, + offset: 0, + }); + + // ASSERT + const expectedResponse: Comments = { + 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); + }); +}); diff --git a/src/comments/getCommentsOnGameWall.test.ts b/src/comments/getCommentsOnGameWall.test.ts new file mode 100644 index 0000000..38ae567 --- /dev/null +++ b/src/comments/getCommentsOnGameWall.test.ts @@ -0,0 +1,81 @@ +/* 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 { getCommentsOnGameWall } from "./getCommentsOnGameWall"; +import type { Comments, GetCommentsResponse } from "./models"; + +const server = setupServer(); + +describe("Function: getCommentsOnGameWall", () => { + // MSW Setup + beforeAll(() => server.listen()); + afterEach(() => server.resetHandlers()); + afterAll(() => server.close()); + + it("is defined #sanity", () => { + // ASSERT + expect(getCommentsOnGameWall).toBeDefined(); + }); + + it("retrieves the comments on an game and cleans properties", 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 getCommentsOnGameWall(authorization, { + gameId: 321_865, + count: 2, + offset: 0, + }); + + // ASSERT + const expectedResponse: Comments = { + 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); + }); +}); diff --git a/src/comments/getCommentsOnUserWall.test.ts b/src/comments/getCommentsOnUserWall.test.ts new file mode 100644 index 0000000..624ba3e --- /dev/null +++ b/src/comments/getCommentsOnUserWall.test.ts @@ -0,0 +1,81 @@ +/* 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 { getCommentsOnUserWall } from "./getCommentsOnUserWall"; +import type { Comments, GetCommentsResponse } from "./models"; + +const server = setupServer(); + +describe("Function: getCommentsOnUserWall", () => { + // MSW Setup + beforeAll(() => server.listen()); + afterEach(() => server.resetHandlers()); + afterAll(() => server.close()); + + it("is defined #sanity", () => { + // ASSERT + expect(getCommentsOnUserWall).toBeDefined(); + }); + + it("retrieves the comments on an user wall and cleans properties", 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 getCommentsOnUserWall(authorization, { + username: "xelnia", + count: 2, + offset: 0, + }); + + // ASSERT + const expectedResponse: Comments = { + 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); + }); +}); From 27f5e34fdcb5966ea5723de57e7085207f792702 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 18:08:36 -0400 Subject: [PATCH 08/18] test: ensure offset is tested in comment tests --- src/comments/getCommentsOnAchievementWall.test.ts | 2 +- src/comments/getCommentsOnGameWall.test.ts | 2 +- src/comments/getCommentsOnUserWall.test.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/comments/getCommentsOnAchievementWall.test.ts b/src/comments/getCommentsOnAchievementWall.test.ts index 508ad2a..a4f4bbf 100644 --- a/src/comments/getCommentsOnAchievementWall.test.ts +++ b/src/comments/getCommentsOnAchievementWall.test.ts @@ -55,7 +55,7 @@ describe("Function: getCommentsOnAchievementWall", () => { const response = await getCommentsOnAchievementWall(authorization, { achievementId: 321_865, count: 2, - offset: 0, + offset: 2, }); // ASSERT diff --git a/src/comments/getCommentsOnGameWall.test.ts b/src/comments/getCommentsOnGameWall.test.ts index 38ae567..f8bbdcf 100644 --- a/src/comments/getCommentsOnGameWall.test.ts +++ b/src/comments/getCommentsOnGameWall.test.ts @@ -55,7 +55,7 @@ describe("Function: getCommentsOnGameWall", () => { const response = await getCommentsOnGameWall(authorization, { gameId: 321_865, count: 2, - offset: 0, + offset: 2, }); // ASSERT diff --git a/src/comments/getCommentsOnUserWall.test.ts b/src/comments/getCommentsOnUserWall.test.ts index 624ba3e..e8a8372 100644 --- a/src/comments/getCommentsOnUserWall.test.ts +++ b/src/comments/getCommentsOnUserWall.test.ts @@ -55,7 +55,7 @@ describe("Function: getCommentsOnUserWall", () => { const response = await getCommentsOnUserWall(authorization, { username: "xelnia", count: 2, - offset: 0, + offset: 2, }); // ASSERT From 73a3a606d3b508c952d2fc92d778d2afcf1095a7 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 18:12:47 -0400 Subject: [PATCH 09/18] chore: update README with new api functions --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index c3fbe2e..c221a49 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,12 @@ Click the function names to open their complete docs on the docs site. - [`getRecentGameAwards()`](https://api-docs.retroachievements.org/v1/get-recent-game-awards.html) - Get all recent mastery, completion, and beaten awards earned on the site. - [`getTopTenUsers()`](https://api-docs.retroachievements.org/v1/get-top-ten-users.html) - Get the list of top ten points earners. +### Comment + +- [`getCommentsOnAchievementWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-achievement-wall.html) - Get the comments left on an achievement's wall. +- [`getCommentsOnGameWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-game-wall.html) - Get the comments left on a game's wall. +- [`getCommentsOnUserWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-user-wall.html) - Get the comments left on a user's wall. + ### Event - [`getAchievementOfTheWeek()`](https://api-docs.retroachievements.org/v1/get-achievement-of-the-week.html) - Get comprehensive metadata about the current Achievement of the Week. From 2f1d0914e3f45ffdfcea67a3c13a8d681ed85959 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 20:01:17 -0400 Subject: [PATCH 10/18] feat: add overarching getComments function --- src/comments/getComments.test.ts | 239 +++++++++++++++++++++++++++++++ src/comments/getComments.ts | 85 +++++++++++ src/comments/index.ts | 1 + 3 files changed, 325 insertions(+) create mode 100644 src/comments/getComments.test.ts create mode 100644 src/comments/getComments.ts diff --git a/src/comments/getComments.test.ts b/src/comments/getComments.test.ts new file mode 100644 index 0000000..f7ef4df --- /dev/null +++ b/src/comments/getComments.test.ts @@ -0,0 +1,239 @@ +/* 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 { Comments, 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: Comments = { + 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 or achievement", 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, + }); + + // ASSERT + const expectedResponse: Comments = { + 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 or 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, + }); + + // ASSERT + const expectedResponse: Comments = { + 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 or achievement, 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, + }); + + // ASSERT + const expectedResponse: Comments = { + count: 1, + total: 2, + results: [ + { + user: "PlayTester", + submitted: "2024-07-31T11:22:23.000000Z", + commentText: "Comment 2", + }, + ], + }; + + expect(response).toEqual(expectedResponse); + }); +}); diff --git a/src/comments/getComments.ts b/src/comments/getComments.ts new file mode 100644 index 0000000..51388f9 --- /dev/null +++ b/src/comments/getComments.ts @@ -0,0 +1,85 @@ +import type { ID } from "../utils/internal"; +import { + apiBaseUrl, + buildRequestUrl, + call, + serializeProperties, +} from "../utils/internal"; +import type { AuthObject } from "../utils/public"; +import type { Comments, GetCommentsResponse } 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.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, 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 | string; offset?: number; count?: number } +): Promise => { + const { identifier, offset, count } = payload; + + const queryParams: Record = { i: identifier, t: 1 }; + + if (offset) { + queryParams.o = offset; + } + + if (count) { + queryParams.c = count; + } + + const url = buildRequestUrl( + apiBaseUrl, + "/API_GetComments.php", + authorization, + queryParams + ); + + const rawResponse = await call({ url }); + + return serializeProperties(rawResponse, { + shouldCastToNumbers: ["Count", "Total"], + }); +}; diff --git a/src/comments/index.ts b/src/comments/index.ts index 70d9dfb..90e4afc 100644 --- a/src/comments/index.ts +++ b/src/comments/index.ts @@ -1,3 +1,4 @@ +export * from "./getComments"; export * from "./getCommentsOnAchievementWall"; export * from "./getCommentsOnGameWall"; export * from "./getCommentsOnUserWall"; From 109c8b9a8157c701731ef6543112466eabaa8fe5 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 20:02:22 -0400 Subject: [PATCH 11/18] chore: remove old 'split' api functions --- .../getCommentsOnAchievementWall.test.ts | 81 ------------------- src/comments/getCommentsOnAchievementWall.ts | 79 ------------------ src/comments/getCommentsOnGameWall.test.ts | 81 ------------------- src/comments/getCommentsOnGameWall.ts | 76 ----------------- src/comments/getCommentsOnUserWall.test.ts | 81 ------------------- src/comments/getCommentsOnUserWall.ts | 71 ---------------- src/comments/index.ts | 3 - 7 files changed, 472 deletions(-) delete mode 100644 src/comments/getCommentsOnAchievementWall.test.ts delete mode 100644 src/comments/getCommentsOnAchievementWall.ts delete mode 100644 src/comments/getCommentsOnGameWall.test.ts delete mode 100644 src/comments/getCommentsOnGameWall.ts delete mode 100644 src/comments/getCommentsOnUserWall.test.ts delete mode 100644 src/comments/getCommentsOnUserWall.ts diff --git a/src/comments/getCommentsOnAchievementWall.test.ts b/src/comments/getCommentsOnAchievementWall.test.ts deleted file mode 100644 index a4f4bbf..0000000 --- a/src/comments/getCommentsOnAchievementWall.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -/* 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 { getCommentsOnAchievementWall } from "./getCommentsOnAchievementWall"; -import type { Comments, GetCommentsResponse } from "./models"; - -const server = setupServer(); - -describe("Function: getCommentsOnAchievementWall", () => { - // MSW Setup - beforeAll(() => server.listen()); - afterEach(() => server.resetHandlers()); - afterAll(() => server.close()); - - it("is defined #sanity", () => { - // ASSERT - expect(getCommentsOnAchievementWall).toBeDefined(); - }); - - it("retrieves the comments on an achievement and cleans properties", 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 getCommentsOnAchievementWall(authorization, { - achievementId: 321_865, - count: 2, - offset: 2, - }); - - // ASSERT - const expectedResponse: Comments = { - 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); - }); -}); diff --git a/src/comments/getCommentsOnAchievementWall.ts b/src/comments/getCommentsOnAchievementWall.ts deleted file mode 100644 index 6d883ac..0000000 --- a/src/comments/getCommentsOnAchievementWall.ts +++ /dev/null @@ -1,79 +0,0 @@ -import type { ID } from "../utils/internal"; -import { - apiBaseUrl, - buildRequestUrl, - call, - serializeProperties, -} from "../utils/internal"; -import type { AuthObject } from "../utils/public"; -import type { Comments, GetCommentsResponse } from "./models"; - -/** - * A call to this function will retrieve a list of comments on a achievement. - * - * @param authorization An object containing your username and webApiKey. - * This can be constructed with `buildAuthorization()`. - * - * @param payload.achievementId The achievement ID to get the comments for. - * - * @param payload.offset Defaults to 0. The number of entries to skip. - * - * @param payload.count Defaults to 50, has a max of 500. - * - * @example - * ``` - * const achievementComments = await getCommentsOnAchievementWall( - * authorization, - * { achievementId: 321865, 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 getCommentsOnAchievementWall = async ( - authorization: AuthObject, - payload: { achievementId: ID; offset?: number; count?: number } -): Promise => { - const { achievementId, offset, count } = payload; - - const queryParams: Record = { - i: achievementId, - t: 2, - }; - - if (offset) { - queryParams.o = offset; - } - - if (count) { - queryParams.c = count; - } - - const url = buildRequestUrl( - apiBaseUrl, - "/API_GetComments.php", - authorization, - queryParams - ); - - const rawResponse = await call({ url }); - - return serializeProperties(rawResponse, { - shouldCastToNumbers: ["Count", "Total"], - }); -}; diff --git a/src/comments/getCommentsOnGameWall.test.ts b/src/comments/getCommentsOnGameWall.test.ts deleted file mode 100644 index f8bbdcf..0000000 --- a/src/comments/getCommentsOnGameWall.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -/* 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 { getCommentsOnGameWall } from "./getCommentsOnGameWall"; -import type { Comments, GetCommentsResponse } from "./models"; - -const server = setupServer(); - -describe("Function: getCommentsOnGameWall", () => { - // MSW Setup - beforeAll(() => server.listen()); - afterEach(() => server.resetHandlers()); - afterAll(() => server.close()); - - it("is defined #sanity", () => { - // ASSERT - expect(getCommentsOnGameWall).toBeDefined(); - }); - - it("retrieves the comments on an game and cleans properties", 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 getCommentsOnGameWall(authorization, { - gameId: 321_865, - count: 2, - offset: 2, - }); - - // ASSERT - const expectedResponse: Comments = { - 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); - }); -}); diff --git a/src/comments/getCommentsOnGameWall.ts b/src/comments/getCommentsOnGameWall.ts deleted file mode 100644 index 9c48e4a..0000000 --- a/src/comments/getCommentsOnGameWall.ts +++ /dev/null @@ -1,76 +0,0 @@ -import type { ID } from "../utils/internal"; -import { - apiBaseUrl, - buildRequestUrl, - call, - serializeProperties, -} from "../utils/internal"; -import type { AuthObject } from "../utils/public"; -import type { Comments, GetCommentsResponse } from "./models"; - -/** - * A call to this function will retrieve a list of comments on a game's page. - * - * @param authorization An object containing your username and webApiKey. - * This can be constructed with `buildAuthorization()`. - * - * @param payload.gameId The gameId ID to get the comments for. - * - * @param payload.offset Defaults to 0. The number of entries to skip. - * - * @param payload.count Defaults to 50, has a max of 500. - * - * @example - * ``` - * const gameWallComments = await getCommentsOnGameWall( - * authorization, - * { gameId: 20294, 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 getCommentsOnGameWall = async ( - authorization: AuthObject, - payload: { gameId: ID; offset?: number; count?: number } -): Promise => { - const { gameId, offset, count } = payload; - - const queryParams: Record = { i: gameId, t: 1 }; - - if (offset) { - queryParams.o = offset; - } - - if (count) { - queryParams.c = count; - } - - const url = buildRequestUrl( - apiBaseUrl, - "/API_GetComments.php", - authorization, - queryParams - ); - - const rawResponse = await call({ url }); - - return serializeProperties(rawResponse, { - shouldCastToNumbers: ["Count", "Total"], - }); -}; diff --git a/src/comments/getCommentsOnUserWall.test.ts b/src/comments/getCommentsOnUserWall.test.ts deleted file mode 100644 index e8a8372..0000000 --- a/src/comments/getCommentsOnUserWall.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -/* 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 { getCommentsOnUserWall } from "./getCommentsOnUserWall"; -import type { Comments, GetCommentsResponse } from "./models"; - -const server = setupServer(); - -describe("Function: getCommentsOnUserWall", () => { - // MSW Setup - beforeAll(() => server.listen()); - afterEach(() => server.resetHandlers()); - afterAll(() => server.close()); - - it("is defined #sanity", () => { - // ASSERT - expect(getCommentsOnUserWall).toBeDefined(); - }); - - it("retrieves the comments on an user wall and cleans properties", 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 getCommentsOnUserWall(authorization, { - username: "xelnia", - count: 2, - offset: 2, - }); - - // ASSERT - const expectedResponse: Comments = { - 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); - }); -}); diff --git a/src/comments/getCommentsOnUserWall.ts b/src/comments/getCommentsOnUserWall.ts deleted file mode 100644 index befe18b..0000000 --- a/src/comments/getCommentsOnUserWall.ts +++ /dev/null @@ -1,71 +0,0 @@ -import { - apiBaseUrl, - buildRequestUrl, - call, - serializeProperties, -} from "../utils/internal"; -import type { AuthObject } from "../utils/public"; -import type { Comments, GetCommentsResponse } from "./models"; - -/** - * A call to this function will retrieve a list of comments on a user's wall. - * - * @param authorization An object containing your username and webApiKey. - * This can be constructed with `buildAuthorization()`. - * - * @param payload.username The username to get the comments wall for. - * - * @example - * ``` - * const userWallComments = await getCommentsOnUserWall( - * authorization, - * { username: "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 getCommentsOnUserWall = async ( - authorization: AuthObject, - payload: { username: string; offset?: number; count?: number } -): Promise => { - const { username, offset, count } = payload; - - const queryParams: Record = { i: username }; - - if (offset) { - queryParams.o = offset; - } - - if (count) { - queryParams.c = count; - } - - const url = buildRequestUrl( - apiBaseUrl, - "/API_GetComments.php", - authorization, - queryParams - ); - - const rawResponse = await call({ url }); - - return serializeProperties(rawResponse, { - shouldCastToNumbers: ["Count", "Total"], - }); -}; diff --git a/src/comments/index.ts b/src/comments/index.ts index 90e4afc..397b938 100644 --- a/src/comments/index.ts +++ b/src/comments/index.ts @@ -1,5 +1,2 @@ export * from "./getComments"; -export * from "./getCommentsOnAchievementWall"; -export * from "./getCommentsOnGameWall"; -export * from "./getCommentsOnUserWall"; export * from "./models"; From 4e7e63e5d8fd182e4920c547999135f4b63226e4 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 20:30:04 -0400 Subject: [PATCH 12/18] docs: replace old functions with single getComments function --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index c221a49..206ff62 100644 --- a/README.md +++ b/README.md @@ -119,9 +119,7 @@ Click the function names to open their complete docs on the docs site. ### Comment -- [`getCommentsOnAchievementWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-achievement-wall.html) - Get the comments left on an achievement's wall. -- [`getCommentsOnGameWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-game-wall.html) - Get the comments left on a game's wall. -- [`getCommentsOnUserWall()`](https://api-docs.retroachievements.org/v1/get-comments-on-user-wall.html) - Get the comments left on a user's wall. +- [`getComments()`](https://api-docs.retroachievements.org/v1/get-comments.html) - Get the comments left an achievement, game, or user wall. ### Event From 82b1fdcf9b2bf11cce9e3869dbd6b4dc9c1e07f8 Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 20:31:02 -0400 Subject: [PATCH 13/18] feat: add parameter for 'kind', and test for it missing when needed --- src/comments/getComments.test.ts | 44 +++++++++++++++++++++++++++++--- src/comments/getComments.ts | 17 +++++++++--- 2 files changed, 55 insertions(+), 6 deletions(-) diff --git a/src/comments/getComments.test.ts b/src/comments/getComments.test.ts index f7ef4df..6170a80 100644 --- a/src/comments/getComments.test.ts +++ b/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); + }); }); diff --git a/src/comments/getComments.ts b/src/comments/getComments.ts index 51388f9..5e566c4 100644 --- a/src/comments/getComments.ts +++ b/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 => { - const { identifier, offset, count } = payload; + const { identifier, kind, offset, count } = payload; + + const queryParams: Record = { i: identifier }; - const queryParams: Record = { 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; From 0a8546f9e3a4de579bb30252169fc96bd1c654fa Mon Sep 17 00:00:00 2001 From: bram Date: Sun, 9 Mar 2025 20:37:46 -0400 Subject: [PATCH 14/18] docs: document the need to specify kind in getComments signature example --- src/comments/getComments.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/comments/getComments.ts b/src/comments/getComments.ts index 5e566c4..d4ff7e5 100644 --- a/src/comments/getComments.ts +++ b/src/comments/getComments.ts @@ -30,7 +30,7 @@ import type { Comments, GetCommentsResponse } from "./models"; * // Retrieving game/achievement comments * const gameWallComments = await getComments( * authorization, - * { identifier: 20294, count: 4, offset: 0 }, + * { identifier: 20294, kind: 1 count: 4, offset: 0 }, * ); * * // Retrieving comments on a user's wall From 947ab3cb31ad8c74fefa5f61c155de667de066e5 Mon Sep 17 00:00:00 2001 From: bram Date: Mon, 10 Mar 2025 21:13:23 -0400 Subject: [PATCH 15/18] refactor: src/comments->src/comment --- src/{comments => comment}/getComments.test.ts | 0 src/{comments => comment}/getComments.ts | 2 +- src/{comments => comment}/index.ts | 0 src/{comments => comment}/models/comments.model.ts | 0 src/{comments => comment}/models/get-comments-response.ts | 0 src/{comments => comment}/models/index.ts | 0 src/index.ts | 2 +- 7 files changed, 2 insertions(+), 2 deletions(-) rename src/{comments => comment}/getComments.test.ts (100%) rename src/{comments => comment}/getComments.ts (97%) rename src/{comments => comment}/index.ts (100%) rename src/{comments => comment}/models/comments.model.ts (100%) rename src/{comments => comment}/models/get-comments-response.ts (100%) rename src/{comments => comment}/models/index.ts (100%) diff --git a/src/comments/getComments.test.ts b/src/comment/getComments.test.ts similarity index 100% rename from src/comments/getComments.test.ts rename to src/comment/getComments.test.ts diff --git a/src/comments/getComments.ts b/src/comment/getComments.ts similarity index 97% rename from src/comments/getComments.ts rename to src/comment/getComments.ts index d4ff7e5..601f925 100644 --- a/src/comments/getComments.ts +++ b/src/comment/getComments.ts @@ -30,7 +30,7 @@ import type { Comments, GetCommentsResponse } from "./models"; * // Retrieving game/achievement comments * const gameWallComments = await getComments( * authorization, - * { identifier: 20294, kind: 1 count: 4, offset: 0 }, + * { identifier: 20294, kind: 1, count: 4, offset: 0 }, * ); * * // Retrieving comments on a user's wall diff --git a/src/comments/index.ts b/src/comment/index.ts similarity index 100% rename from src/comments/index.ts rename to src/comment/index.ts diff --git a/src/comments/models/comments.model.ts b/src/comment/models/comments.model.ts similarity index 100% rename from src/comments/models/comments.model.ts rename to src/comment/models/comments.model.ts diff --git a/src/comments/models/get-comments-response.ts b/src/comment/models/get-comments-response.ts similarity index 100% rename from src/comments/models/get-comments-response.ts rename to src/comment/models/get-comments-response.ts diff --git a/src/comments/models/index.ts b/src/comment/models/index.ts similarity index 100% rename from src/comments/models/index.ts rename to src/comment/models/index.ts diff --git a/src/index.ts b/src/index.ts index 8ded3a1..82bbcfb 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,7 @@ // This file is the single public-facing API of the entire library. export * from "./achievement"; -export * from "./comments"; +export * from "./comment"; export * from "./console"; export * from "./feed"; export * from "./game"; From 5d8aafe4aaf57174ce7a71cfed21ee3896be365f Mon Sep 17 00:00:00 2001 From: bram Date: Mon, 10 Mar 2025 21:46:58 -0400 Subject: [PATCH 16/18] refactor: use kindmap for kind --- src/comment/getComments.ts | 21 ++++++++++++++----- ...onse.ts => get-comments-response.model.ts} | 0 src/comment/models/index.ts | 2 +- 3 files changed, 17 insertions(+), 6 deletions(-) rename src/comment/models/{get-comments-response.ts => get-comments-response.model.ts} (100%) diff --git a/src/comment/getComments.ts b/src/comment/getComments.ts index 601f925..1b6e6a4 100644 --- a/src/comment/getComments.ts +++ b/src/comment/getComments.ts @@ -8,6 +8,12 @@ import { import type { AuthObject } from "../utils/public"; import type { Comments, 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. * @@ -18,8 +24,8 @@ 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.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. * @@ -30,7 +36,7 @@ import type { Comments, GetCommentsResponse } from "./models"; * // Retrieving game/achievement comments * const gameWallComments = await getComments( * authorization, - * { identifier: 20294, kind: 1, count: 4, offset: 0 }, + * { identifier: 20294, kind: 'game', count: 4, offset: 0 }, * ); * * // Retrieving comments on a user's wall @@ -59,14 +65,19 @@ import type { Comments, GetCommentsResponse } from "./models"; */ export const getComments = async ( authorization: AuthObject, - payload: { identifier: ID; kind?: number; offset?: number; count?: number } + payload: { + identifier: ID; + kind?: "game" | "achievement" | "user"; + offset?: number; + count?: number; + } ): Promise => { const { identifier, kind, offset, count } = payload; const queryParams: Record = { i: identifier }; if (kind) { - queryParams.t = kind; + queryParams.t = kindMap[kind]; } else if (typeof identifier === "number") { throw new TypeError( "'kind' must be specified when looking up an achievement or game." diff --git a/src/comment/models/get-comments-response.ts b/src/comment/models/get-comments-response.model.ts similarity index 100% rename from src/comment/models/get-comments-response.ts rename to src/comment/models/get-comments-response.model.ts diff --git a/src/comment/models/index.ts b/src/comment/models/index.ts index fb4394f..6cb347c 100644 --- a/src/comment/models/index.ts +++ b/src/comment/models/index.ts @@ -1,2 +1,2 @@ export * from "./comments.model"; -export * from "./get-comments-response"; +export * from "./get-comments-response.model"; From 91586b50ede4c69ca30c188fd2735761b6758408 Mon Sep 17 00:00:00 2001 From: bram Date: Mon, 10 Mar 2025 21:48:45 -0400 Subject: [PATCH 17/18] refactor: rename models --- src/comment/models/{comments.model.ts => comment-entity.model.ts} | 0 .../{get-comments-response.model.ts => comment-response.model.ts} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename src/comment/models/{comments.model.ts => comment-entity.model.ts} (100%) rename src/comment/models/{get-comments-response.model.ts => comment-response.model.ts} (100%) diff --git a/src/comment/models/comments.model.ts b/src/comment/models/comment-entity.model.ts similarity index 100% rename from src/comment/models/comments.model.ts rename to src/comment/models/comment-entity.model.ts diff --git a/src/comment/models/get-comments-response.model.ts b/src/comment/models/comment-response.model.ts similarity index 100% rename from src/comment/models/get-comments-response.model.ts rename to src/comment/models/comment-response.model.ts From 419182920524c5720f4de1958108702042410371 Mon Sep 17 00:00:00 2001 From: bram Date: Mon, 10 Mar 2025 21:57:25 -0400 Subject: [PATCH 18/18] refactor: update types names/definitions for easier dx --- src/comment/getComments.test.ts | 16 ++++++++-------- src/comment/getComments.ts | 4 ++-- src/comment/models/comment-entity.model.ts | 9 +-------- src/comment/models/comment-response.model.ts | 16 +++++----------- .../models/get-comments-response.model.ts | 13 +++++++++++++ src/comment/models/index.ts | 3 ++- 6 files changed, 31 insertions(+), 30 deletions(-) create mode 100644 src/comment/models/get-comments-response.model.ts diff --git a/src/comment/getComments.test.ts b/src/comment/getComments.test.ts index 6170a80..03a361b 100644 --- a/src/comment/getComments.test.ts +++ b/src/comment/getComments.test.ts @@ -6,7 +6,7 @@ import { setupServer } from "msw/node"; import { apiBaseUrl } from "../utils/internal"; import { buildAuthorization } from "../utils/public"; import { getComments } from "./getComments"; -import type { Comments, GetCommentsResponse } from "./models"; +import type { CommentsResponse, GetCommentsResponse } from "./models"; const server = setupServer(); @@ -57,7 +57,7 @@ describe("Function: getComments", () => { }); // ASSERT - const expectedResponse: Comments = { + const expectedResponse: CommentsResponse = { count: 2, total: 2, results: [ @@ -110,11 +110,11 @@ describe("Function: getComments", () => { // ACT const response = await getComments(authorization, { identifier: 321_865, - kind: 1, + kind: "game", }); // ASSERT - const expectedResponse: Comments = { + const expectedResponse: CommentsResponse = { count: 2, total: 2, results: [ @@ -168,11 +168,11 @@ describe("Function: getComments", () => { const response = await getComments(authorization, { identifier: 321_865, count: 2, - kind: 2, + kind: "achievement", }); // ASSERT - const expectedResponse: Comments = { + const expectedResponse: CommentsResponse = { count: 2, total: 4, results: [ @@ -221,11 +221,11 @@ describe("Function: getComments", () => { const response = await getComments(authorization, { identifier: 321_865, offset: 1, - kind: 1, + kind: "game", }); // ASSERT - const expectedResponse: Comments = { + const expectedResponse: CommentsResponse = { count: 1, total: 2, results: [ diff --git a/src/comment/getComments.ts b/src/comment/getComments.ts index 1b6e6a4..a8a3522 100644 --- a/src/comment/getComments.ts +++ b/src/comment/getComments.ts @@ -6,7 +6,7 @@ import { serializeProperties, } from "../utils/internal"; import type { AuthObject } from "../utils/public"; -import type { Comments, GetCommentsResponse } from "./models"; +import type { CommentsResponse, GetCommentsResponse } from "./models"; const kindMap: Record<"game" | "achievement" | "user", number> = { game: 1, @@ -71,7 +71,7 @@ export const getComments = async ( offset?: number; count?: number; } -): Promise => { +): Promise => { const { identifier, kind, offset, count } = payload; const queryParams: Record = { i: identifier }; diff --git a/src/comment/models/comment-entity.model.ts b/src/comment/models/comment-entity.model.ts index 6ffe081..f203b46 100644 --- a/src/comment/models/comment-entity.model.ts +++ b/src/comment/models/comment-entity.model.ts @@ -1,14 +1,7 @@ -interface CommentEntity { +export interface CommentEntity { user: string; submitted: string; commentText: string; } -interface CommentsEntity { - count: number; - total: number; - results: CommentEntity[]; -} - -export type Comments = CommentsEntity; export type Comment = CommentEntity; diff --git a/src/comment/models/comment-response.model.ts b/src/comment/models/comment-response.model.ts index 0d3dd25..2f65cf0 100644 --- a/src/comment/models/comment-response.model.ts +++ b/src/comment/models/comment-response.model.ts @@ -1,13 +1,7 @@ -interface RawComment { - User: string; - Submitted: string; - CommentText: string; -} +import type { CommentEntity } from "./comment-entity.model"; -interface RawCommentsResponseEntity { - Count: number; - Total: number; - Results: RawComment[]; +export interface CommentsResponse { + count: number; + total: number; + results: CommentEntity[]; } - -export type GetCommentsResponse = RawCommentsResponseEntity; diff --git a/src/comment/models/get-comments-response.model.ts b/src/comment/models/get-comments-response.model.ts new file mode 100644 index 0000000..1aeb03b --- /dev/null +++ b/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; diff --git a/src/comment/models/index.ts b/src/comment/models/index.ts index 6cb347c..3d9301c 100644 --- a/src/comment/models/index.ts +++ b/src/comment/models/index.ts @@ -1,2 +1,3 @@ -export * from "./comments.model"; +export * from "./comment-entity.model"; +export * from "./comment-response.model"; export * from "./get-comments-response.model";