@retroachievements/api 2.5.0 → 2.7.0

package/dist/leaderboard/models/get-user-game-leaderboards-response.model.d.ts

@@ -0,0 +1,19 @@
+export interface GetUserGameLeaderboardsResponse {
+    Count: number;
+    Total: number;
+    Results: Array<{
+        ID: number;
+        RankAsc: boolean;
+        Title: string;
+        Description: string;
+        Format: string;
+        UserEntry: {
+            User: string;
+            ULID: string;
+            Score: number;
+            FormattedScore: string;
+            Rank: number;
+            DateUpdated: string;
+        };
+    }>;
+}

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

@@ -1,2 +1,4 @@
 export * from "./get-leaderboard-entries-response.model";
+export * from "./get-user-game-leaderboards-response.model";
 export * from "./leaderboard-entries.model";
+export * from "./user-game-leaderboards.model";

package/dist/leaderboard/models/user-game-leaderboards.model.d.ts

@@ -0,0 +1,19 @@
+export interface UserGameLeaderboards {
+    count: number;
+    total: number;
+    results: Array<{
+        id: number;
+        rankAsc: boolean;
+        title: string;
+        description: string;
+        format: string;
+        userEntry: {
+            user: string;
+            ulid: string;
+            score: number;
+            formattedScore: string;
+            rank: number;
+            dateUpdated: string;
+        };
+    }>;
+}

package/dist/user/models/get-user-recent-achievements-response.model.d.ts

@@ -1,3 +1,4 @@
+import type { AchievementType } from "../../achievement";
 interface GetUserRecentAchievementsEntity {
     Date: string;
     HardcoreMode: 0 | 1;
@@ -6,7 +7,10 @@ interface GetUserRecentAchievementsEntity {
     Description: string;
     BadgeName: string;
     Points: number;
+    TrueRatio: number;
+    Type: AchievementType;
     Author: string;
+    AuthorULID: string;
     GameTitle: string;
     GameIcon: string;
     GameID: number;

package/dist/user/models/user-recent-achievement.model.d.ts

@@ -1,3 +1,4 @@
+import type { AchievementType } from "../../achievement";
 export interface UserRecentAchievement {
     date: string;
     hardcoreMode: boolean;
@@ -6,7 +7,10 @@ export interface UserRecentAchievement {
     description: string;
     badgeName: string;
     points: number;
+    trueRatio: number;
+    type: AchievementType;
     author: string;
+    authorUlid: string;
     gameTitle: string;
     gameIcon: string;
     gameId: number;

package/package.json

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

package/src/game/models/get-game-hashes-response.model.ts

@@ -2,7 +2,7 @@ interface GameHashResult {
   MD5: string;
   Name: string;
   Labels: string[];
-  PatchUrl: string;
+  PatchUrl: string | null;
 }
 
 export interface GetGameHashesResponse {

package/src/leaderboard/getUserGameLeaderboards.test.ts

@@ -0,0 +1,88 @@
+/* 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 { getUserGameLeaderboards } from "./getUserGameLeaderboards";
+import type { GetUserGameLeaderboardsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserGameLeaderboards", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserGameLeaderboards).toBeDefined();
+  });
+
+  it("given a game ID, retrieves the users leaderboards", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse: GetUserGameLeaderboardsResponse = {
+      Count: 10,
+      Total: 64,
+      Results: [
+        {
+          ID: 19_062,
+          RankAsc: true,
+          Title: "New Zealand One",
+          Description: "Complete New Zealand S1 in least time",
+          Format: "MILLISECS",
+          UserEntry: {
+            User: "zuliman92",
+            ULID: "00003EMFWR7XB8SDPEHB3K56ZQ",
+            Score: 12_620,
+            FormattedScore: "2:06.20",
+            Rank: 2,
+            DateUpdated: "2024-12-12T16:40:59+00:00",
+          },
+        },
+      ],
+    };
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUserGameLeaderboards.php`, () =>
+        HttpResponse.json(mockResponse)
+      )
+    );
+
+    // ACT
+    const response = await getUserGameLeaderboards(authorization, {
+      gameId: 1,
+      username: "zuliman92",
+    });
+
+    // ASSERT
+    expect(response).toEqual({
+      count: 10,
+      total: 64,
+      results: [
+        {
+          id: 19_062,
+          rankAsc: true,
+          title: "New Zealand One",
+          description: "Complete New Zealand S1 in least time",
+          format: "MILLISECS",
+          userEntry: {
+            user: "zuliman92",
+            ulid: "00003EMFWR7XB8SDPEHB3K56ZQ",
+            score: 12_620,
+            formattedScore: "2:06.20",
+            rank: 2,
+            dateUpdated: "2024-12-12T16:40:59+00:00",
+          },
+        },
+      ],
+    });
+  });
+});

package/src/leaderboard/getUserGameLeaderboards.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 {
+  GetUserGameLeaderboardsResponse,
+  UserGameLeaderboards,
+} from "./models";
+
+/**
+ * A call to this endpoint will retrieve a user's list of leaderboards for a given game, targeted by the game's ID.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.gameId The target game ID.
+ *
+ * @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 gameLeaderboards = await getUserGameLeaderboards(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object containing user game leaderboard's.
+ * ```json
+ * {
+ *   "count": 10,
+ *   "total": 64,
+ *   "results": [
+ *     {
+ *       "id": 19062,
+ *       "rankAsc": true,
+ *       "title": "New Zealand One",
+ *       "description": "Complete New Zealand S1 in least time",
+ *       "format": "MILLISECS",
+ *       "userEntry": {
+ *         "user": "zuliman92",
+ *         "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
+ *         "score": 12620,
+ *         "formattedScore": "2:06.20",
+ *         "rank": 2,
+ *         "dateUpdated": "2024-12-12T16:40:59+00:00"
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const getUserGameLeaderboards = async (
+  authorization: AuthObject,
+  payload: { gameId: ID; username?: string; offset?: number; count?: number }
+): Promise<UserGameLeaderboards> => {
+  const queryParams: Record<string, any> = {};
+  queryParams.i = payload.gameId;
+  if (payload?.username) {
+    queryParams.u = payload.username;
+  }
+  if (payload?.offset) {
+    queryParams.o = payload.offset;
+  }
+  if (payload?.count) {
+    queryParams.c = payload.count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserGameLeaderboards.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetUserGameLeaderboardsResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};

package/src/leaderboard/models/get-user-game-leaderboards-response.model.ts

@@ -0,0 +1,19 @@
+export interface GetUserGameLeaderboardsResponse {
+  Count: number;
+  Total: number;
+  Results: Array<{
+    ID: number;
+    RankAsc: boolean;
+    Title: string;
+    Description: string;
+    Format: string;
+    UserEntry: {
+      User: string;
+      ULID: string;
+      Score: number;
+      FormattedScore: string;
+      Rank: number;
+      DateUpdated: string;
+    };
+  }>;
+}

package/src/leaderboard/models/index.ts

@@ -1,2 +1,4 @@
 export * from "./get-leaderboard-entries-response.model";
+export * from "./get-user-game-leaderboards-response.model";
 export * from "./leaderboard-entries.model";
+export * from "./user-game-leaderboards.model";

package/src/leaderboard/models/user-game-leaderboards.model.ts

@@ -0,0 +1,19 @@
+export interface UserGameLeaderboards {
+  count: number;
+  total: number;
+  results: Array<{
+    id: number;
+    rankAsc: boolean;
+    title: string;
+    description: string;
+    format: string;
+    userEntry: {
+      user: string;
+      ulid: string;
+      score: number;
+      formattedScore: string;
+      rank: number;
+      dateUpdated: string;
+    };
+  }>;
+}

package/src/user/getUserRecentAchievements.test.ts

@@ -36,7 +36,10 @@ describe("Function: getUserRecentAchievements", () => {
           "Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.",
         BadgeName: "121991",
         Points: 25,
+        TrueRatio: 50,
+        Type: "missable",
         Author: "Som1",
+        AuthorULID: "01F13ZKAPPEZ90K3JK82QWYRN2",
         GameTitle: "WWF King of the Ring",
         GameIcon: "/Images/062599.png",
         GameID: 6316,
@@ -68,7 +71,10 @@ describe("Function: getUserRecentAchievements", () => {
           "Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.",
         badgeName: "121991",
         points: 25,
+        trueRatio: 50,
+        type: "missable",
         author: "Som1",
+        authorUlid: "01F13ZKAPPEZ90K3JK82QWYRN2",
         gameTitle: "WWF King of the Ring",
         gameIcon: "/Images/062599.png",
         gameId: 6316,

package/src/user/models/get-user-recent-achievements-response.model.ts

@@ -1,3 +1,5 @@
+import type { AchievementType } from "../../achievement";
+
 interface GetUserRecentAchievementsEntity {
   Date: string;
   HardcoreMode: 0 | 1;
@@ -6,7 +8,10 @@ interface GetUserRecentAchievementsEntity {
   Description: string;
   BadgeName: string;
   Points: number;
+  TrueRatio: number;
+  Type: AchievementType;
   Author: string;
+  AuthorULID: string;
   GameTitle: string;
   GameIcon: string;
   GameID: number;

package/src/user/models/user-recent-achievement.model.ts

@@ -1,3 +1,5 @@
+import type { AchievementType } from "../../achievement";
+
 export interface UserRecentAchievement {
   date: string;
   hardcoreMode: boolean;
@@ -6,7 +8,10 @@ export interface UserRecentAchievement {
   description: string;
   badgeName: string;
   points: number;
+  trueRatio: number;
+  type: AchievementType;
   author: string;
+  authorUlid: string;
   gameTitle: string;
   gameIcon: string;
   gameId: number;

package/src/utils/internal/serializeProperties.ts

@@ -62,6 +62,9 @@ const naiveCamelCase = (originalValue: string) => {
   let camelCased =
     originalValue.charAt(0).toLowerCase() + originalValue.slice(1);
 
+  // "authorULId" -> "authorUlid"
+  camelCased = camelCased.replaceAll("ULID", "Ulid");
+
   // "gameID" -> "gameId"
   camelCased = camelCased.replaceAll("ID", "Id");