feat(user): add getUserFriendsRequests function to retrieve friends requests (#228)

Author: Dev-R

README.md

@@ -113,6 +113,8 @@ Click the function names to open their complete docs on the docs site.
 - [`getProfileFromAccountId()`](https://psn-api.achievements.app/api-docs/users#getprofilefromaccountid) - Get a user's profile from the `accountId`.
 - [`getUserFriendsAccountIds()`](https://psn-api.achievements.app/api-docs/users#getuserfriendsaccountids) - Get a list
   of `accountId` values present on a target account's friends list.
+- [`getUserFriendsRequests()`](https://psn-api.achievements.app/api-docs/users#getuserfriendsrequests) - Get a list
+  of `accountId` values corresponding to received friend requests for the account the client is logged into.
 - [`getBasicPresence()`](https://psn-api.achievements.app/api-docs/users#getbasicpresence) - Get a user's basic presence
   information.
 - [`getUserRegion()`](https://psn-api.achievements.app/api-docs/users#getuserregion) - Get a user's region information based on their username.

src/models/get-user-friends-requests-response.model.ts

@@ -0,0 +1,7 @@
+export interface GetUserFriendsRequestsResponse {
+  /** A list of `accountId` values corresponding to accounts that have sent friend requests to the user. */
+  receivedRequests: string[];
+
+  /** The total number of friend requests the user has received. */
+  totalItemCount: number;
+}

src/models/index.ts

@@ -4,6 +4,7 @@ export * from "./authorization-payload.model";
 export * from "./basic-presence-response.model";
 export * from "./call-valid-headers.model";
 export * from "./get-user-friends-account-ids-response.model";
+export * from "./get-user-friends-requests-response.model";
 export * from "./membership.model";
 export * from "./profile-from-account-id-response.model";
 export * from "./profile-from-user-name-response.model";

src/user/getUserFriendsRequests.test.ts

@@ -0,0 +1,71 @@
+import nock from "nock";
+
+import type {
+  AuthorizationPayload,
+  GetUserFriendsRequestsResponse
+} from "../models";
+import { getUserFriendsRequests } from "./getUserFriendsRequests";
+import { USER_BASE_URL } from "./USER_BASE_URL";
+
+describe("Function: getUserFriendsRequests", () => {
+  afterEach(() => {
+    nock.cleanAll();
+  });
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserFriendsRequests).toBeDefined();
+  });
+
+  it("retrieves the received friend requests for the authenticated user", async () => {
+    // ARRANGE
+    const mockAuthorization: AuthorizationPayload = {
+      accessToken: "mockAccessToken"
+    };
+
+    const mockResponse: GetUserFriendsRequestsResponse = {
+      receivedRequests: ["2984038888603282554", "8403439712302084350"],
+      totalItemCount: 2
+    };
+
+    const baseUrlObj = new URL(USER_BASE_URL);
+    const baseUrl = `${baseUrlObj.protocol}//${baseUrlObj.host}`;
+    const basePath = baseUrlObj.pathname;
+
+    nock(baseUrl)
+      .get(`${basePath}/me/friends/receivedRequests`)
+      .query(true)
+      .reply(200, mockResponse);
+
+    // ACT
+    const response = await getUserFriendsRequests(mockAuthorization);
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+  });
+
+  it("throws an error if we receive a response containing an `error` object", async () => {
+    // ARRANGE
+    const mockAuthorization: AuthorizationPayload = {
+      accessToken: "mockAccessToken"
+    };
+
+    const mockResponse = {
+      error: {
+        referenceId: "d71bd8ff-5f63-11ec-87da-d5dfd3bc6e67",
+        code: 2_281_604,
+        message: "Not Found"
+      }
+    };
+
+    nock("https://m.np.playstation.com")
+      .get("/api/userProfile/v1/internal/users/me/friends/receivedRequests")
+      .query(true)
+      .reply(200, mockResponse);
+
+    // ASSERT
+    await expect(
+      getUserFriendsRequests(mockAuthorization)
+    ).rejects.toThrow();
+  });
+});

src/user/getUserFriendsRequests.ts

@@ -0,0 +1,43 @@
+import type {
+  AllCallOptions,
+  AuthorizationPayload,
+  GetUserFriendsRequestsResponse
+} from "../models";
+import { buildRequestUrl } from "../utils/buildRequestUrl";
+import { call } from "../utils/call";
+import { USER_BASE_URL } from "./USER_BASE_URL";
+
+type GetUserFriendsRequestsOptions = Pick<AllCallOptions, "limit" | "offset">;
+
+/**
+ * A call to this function will retrieve the list of received friend requests `accountId` values
+ * for the account the client is logged into.
+ *
+ * @param authorization An object containing your access token, typically retrieved with `exchangeAccessCodeForAuthTokens()`.
+ * @param options Optional parameters for pagination (limit and offset).
+ */
+export const getUserFriendsRequests = async (
+  authorization: AuthorizationPayload,
+  options?: Partial<GetUserFriendsRequestsOptions>
+): Promise<GetUserFriendsRequestsResponse> => {
+  const url = buildRequestUrl(
+    USER_BASE_URL,
+    "/:accountId/friends/receivedRequests",
+    options,
+    {
+      accountId: "me" // 'me' is used to refer to the authenticated user's account
+    }
+  );
+
+  const response = await call<GetUserFriendsRequestsResponse>(
+    { url },
+    authorization
+  );
+
+  // If you are unable to access the user's friend requests, an error will be thrown.
+  if ((response as any)?.error) {
+    throw new Error((response as any)?.error?.message ?? "Unexpected Error");
+  }
+
+  return response;
+};

src/user/index.ts

@@ -4,5 +4,6 @@ export * from "./getProfileFromAccountId";
 export * from "./getProfileFromUserName";
 export * from "./getProfileShareableLink";
 export * from "./getUserFriendsAccountIds";
+export * from "./getUserFriendsRequests";
 export * from "./getUserPlayedGames";
 export * from "./getUserRegion";

website/docs/api-docs/users.md

@@ -217,6 +217,48 @@ These are the possible values that can be in the `options` object (the third par
 
 ---
 
+## getUserFriendsRequests
+
+A call to this function will retrieve the list of received friend requests (as `accountId` values) for the account the client is logged into.
+
+### Examples
+
+#### Get received friend requests
+
+```ts
+import { getUserFriendsRequests } from "psn-api";
+
+const response = await getUserFriendsRequests(authorization);
+```
+
+### Returns
+
+| Name               | Type       | Description                                                                      |
+| :----------------- | :--------- | :------------------------------------------------------------------------------- |
+| `receivedRequests` | `string[]` | The `accountId` values of the users who have sent friend requests to your account. |
+| `totalItemCount`   | `number`   | The total number of friend requests received.                                    |
+
+### Parameters
+
+| Name            | Type                                                                  | Description                                                                                                                |
+| :-------------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `authorization` | [`AuthorizationPayload`](/api-docs/data-models/authorization-payload) | An object that must contain an `accessToken`. See [this page](/authentication/authenticating-manually) for how to get one. |
+
+### Options
+
+These are the possible values that can be in the `options` object (the second parameter of the function).
+
+| Name     | Type     | Description                                          |
+| :------- | :------- | :--------------------------------------------------- |
+| `limit`  | `number` | Limit the number of friend requests returned.        |
+| `offset` | `number` | Return friend request data from this result onwards. |
+
+### Source
+
+[user/getUserFriendsRequests.ts](https://github.com/achievements-app/psn-api/blob/main/src/user/getUserFriendsRequests.ts)
+
+---
+
 ## getBasicPresence
 
 A call to this function will retrieve the presence of the accountId being requested. If the user cannot be found (either