@retroachievements/api 2.6.0 → 2.8.0

package/dist/user/getUsersIFollow.d.ts

@@ -0,0 +1,46 @@
+import type { AuthObject } from "../utils/public";
+import type { UsersIFollow } from "./models";
+/**
+ * A call to this function will retrieve the list of users that the
+ * caller is following.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.offset The number of entries to skip. The API will default
+ * to 0 if the parameter is not specified.
+ *
+ * @param payload.count The number of entries to return. The API will
+ * default to 100 if the parameter is not specified. The max number
+ * of entries that can be returned is 500.
+ *
+ * @example
+ * ```
+ * const usersIFollow = await getUsersIFollow(authorization);
+ * ```
+ *
+ * @returns An object containing a list of users that the caller is
+ * following.
+ * ```json
+ * {
+ *   "count": 1,
+ *   "total": 1,
+ *   "results": [
+ *     {
+ *       "user": "Example",
+ *       "ulid": "0123456789ABCDEFGHIJKLMNO",
+ *       "points": 9001,
+ *       "pointsSoftcore": 101,
+ *       "isFollowingMe": false
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @throws If the API was given invalid parameters (422) or if the
+ * API is currently down (503).
+ */
+export declare const getUsersIFollow: (authorization: AuthObject, payload?: {
+    offset?: number;
+    count?: number;
+}) => Promise<UsersIFollow>;

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

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

package/dist/user/index.d.ts

@@ -11,6 +11,7 @@ export * from "./getUserProfile";
 export * from "./getUserProgress";
 export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";
+export * from "./getUsersIFollow";
 export * from "./getUserSummary";
 export * from "./getUserWantToPlayList";
 export * from "./models";

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/get-users-i-follow-response.model.d.ts

@@ -0,0 +1,11 @@
+export interface GetUsersIFollowResponse {
+    Count: number;
+    Total: number;
+    Results: Array<{
+        User: string;
+        ULID: string;
+        Points: number;
+        PointsSoftcore: number;
+        IsFollowingMe: boolean;
+    }>;
+}

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

@@ -14,6 +14,7 @@ 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 "./get-users-i-follow-response.model";
 export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
@@ -28,3 +29,4 @@ 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";
+export * from "./users-i-follow.model";

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/dist/user/models/users-i-follow.model.d.ts

@@ -0,0 +1,11 @@
+export interface UsersIFollow {
+    count: number;
+    total: number;
+    results: Array<{
+        user: string;
+        ulid: string;
+        points: number;
+        pointsSoftcore: number;
+        isFollowingMe: boolean;
+    }>;
+}

package/package.json

@@ -10,7 +10,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "2.6.0",
+  "version": "2.8.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.ts

@@ -58,13 +58,11 @@ import type {
  */
 export const getUserGameLeaderboards = async (
   authorization: AuthObject,
-  payload: { gameId: ID; username?: string; offset?: number; count?: number }
+  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;
-  }
+  queryParams.u = payload.username;
   if (payload?.offset) {
     queryParams.o = payload.offset;
   }

package/src/leaderboard/index.ts

@@ -1,2 +1,3 @@
 export * from "./getLeaderboardEntries";
+export * from "./getUserGameLeaderboards";
 export * from "./models";

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/getUsersIFollow.test.ts

@@ -0,0 +1,124 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUsersIFollow } from "./getUsersIFollow";
+import type { GetUsersIFollowResponse, UsersIFollow } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUsersIFollow", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUsersIFollow).toBeDefined();
+  });
+
+  it("using defaults, retrieves the list of users that the caller follows", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      username: "mockUserName",
+      webApiKey: "mockWebApiKey",
+    });
+
+    const mockResponse = mockGetUsersIFollowResponse;
+
+    server.use(
+      http.get(`${apiBaseUrl}/API_GetUsersIFollow.php`, (info) => {
+        const url = new URL(info.request.url);
+        expect(url.searchParams.has("c")).toBeFalsy();
+        expect(url.searchParams.has("o")).toBeFalsy();
+        return HttpResponse.json(mockResponse);
+      })
+    );
+
+    // ACT
+    const response = await getUsersIFollow(authorization);
+    expect(response).toEqual(mockUsersIFollowValue);
+  });
+
+  it.each([{ offset: 1, count: 1 }, { offset: 5 }, { count: 20 }])(
+    "calls the 'Users I Follow' endpoint with a given offset ($offset) and/or count ($count)",
+    async (mockPayload) => {
+      // ARRANGE
+      const authorization = buildAuthorization({
+        username: "mockUserName",
+        webApiKey: "mockWebApiKey",
+      });
+
+      server.use(
+        http.get(`${apiBaseUrl}/API_GetUsersIFollow.php`, (info) => {
+          const url = new URL(info.request.url);
+          const c = url.searchParams.get("c");
+          const o = url.searchParams.get("o");
+          expect(String(c)).toEqual(String(mockPayload.count ?? null));
+          expect(String(o)).toEqual(String(mockPayload.offset ?? null));
+          return HttpResponse.json(mockGetUsersIFollowResponse);
+        })
+      );
+
+      // ACT
+      await getUsersIFollow(authorization, mockPayload);
+    }
+  );
+
+  it.each([
+    { status: 503, statusText: "The API is currently down" },
+    { status: 422, statusText: "HTTP Error: Status 422 Unprocessable Entity" },
+  ])(
+    "given the API returns a $status, throws an error",
+    async ({ status, statusText }) => {
+      // ARRANGE
+      const authorization = buildAuthorization({
+        username: "mockUserName",
+        webApiKey: "mockWebApiKey",
+      });
+
+      const mockResponse = `<html><body>${statusText}</body></html>`;
+
+      server.use(
+        http.get(`${apiBaseUrl}/API_GetUsersIFollow.php`, () =>
+          HttpResponse.json(mockResponse, { status, statusText })
+        )
+      );
+
+      // ASSERT
+      await expect(
+        getUsersIFollow(authorization, { count: 0 })
+      ).rejects.toThrow();
+    }
+  );
+});
+
+const mockGetUsersIFollowResponse: GetUsersIFollowResponse = {
+  Count: 1,
+  Total: 1,
+  Results: [
+    {
+      User: "Example",
+      ULID: "0123456789ABCDEFGHIJKLMNO",
+      Points: 9001,
+      PointsSoftcore: 101,
+      IsFollowingMe: false,
+    },
+  ],
+};
+
+const mockUsersIFollowValue: UsersIFollow = {
+  count: 1,
+  total: 1,
+  results: [
+    {
+      user: "Example",
+      ulid: "0123456789ABCDEFGHIJKLMNO",
+      points: 9001,
+      pointsSoftcore: 101,
+      isFollowingMe: false,
+    },
+  ],
+};

package/src/user/getUsersIFollow.ts

@@ -0,0 +1,75 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties,
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GetUsersIFollowResponse, UsersIFollow } from "./models";
+
+/**
+ * A call to this function will retrieve the list of users that the
+ * caller is following.
+ *
+ * @param authorization An object containing your username and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.offset The number of entries to skip. The API will default
+ * to 0 if the parameter is not specified.
+ *
+ * @param payload.count The number of entries to return. The API will
+ * default to 100 if the parameter is not specified. The max number
+ * of entries that can be returned is 500.
+ *
+ * @example
+ * ```
+ * const usersIFollow = await getUsersIFollow(authorization);
+ * ```
+ *
+ * @returns An object containing a list of users that the caller is
+ * following.
+ * ```json
+ * {
+ *   "count": 1,
+ *   "total": 1,
+ *   "results": [
+ *     {
+ *       "user": "Example",
+ *       "ulid": "0123456789ABCDEFGHIJKLMNO",
+ *       "points": 9001,
+ *       "pointsSoftcore": 101,
+ *       "isFollowingMe": false
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @throws If the API was given invalid parameters (422) or if the
+ * API is currently down (503).
+ */
+export const getUsersIFollow = async (
+  authorization: AuthObject,
+  payload?: { offset?: number; count?: number }
+): Promise<UsersIFollow> => {
+  const queryParams: Record<string, number> = {};
+  if (payload?.offset !== null && payload?.offset !== undefined) {
+    queryParams.o = payload.offset;
+  }
+  if (payload?.count !== null && payload?.count !== undefined) {
+    queryParams.c = payload.count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUsersIFollow.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetUsersIFollowResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["Points", "PointsSoftcore"],
+    shouldMapToBooleans: ["IsFollowingMe"],
+  });
+};

package/src/user/index.ts

@@ -11,6 +11,7 @@ export * from "./getUserProfile";
 export * from "./getUserProgress";
 export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";
+export * from "./getUsersIFollow";
 export * from "./getUserSummary";
 export * from "./getUserWantToPlayList";
 export * from "./models";

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/get-users-i-follow-response.model.ts

@@ -0,0 +1,11 @@
+export interface GetUsersIFollowResponse {
+  Count: number;
+  Total: number;
+  Results: Array<{
+    User: string;
+    ULID: string;
+    Points: number;
+    PointsSoftcore: number;
+    IsFollowingMe: boolean;
+  }>;
+}

package/src/user/models/index.ts

@@ -14,6 +14,7 @@ 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 "./get-users-i-follow-response.model";
 export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
@@ -28,3 +29,4 @@ 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";
+export * from "./users-i-follow.model";

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/user/models/users-i-follow.model.ts

@@ -0,0 +1,11 @@
+export interface UsersIFollow {
+  count: number;
+  total: number;
+  results: Array<{
+    user: string;
+    ulid: string;
+    points: number;
+    pointsSoftcore: number;
+    isFollowingMe: boolean;
+  }>;
+}

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");