diff --git a/README.md b/README.md index 395957f..f89374f 100644 --- a/README.md +++ b/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. diff --git a/src/models/get-user-friends-requests-response.model.ts b/src/models/get-user-friends-requests-response.model.ts new file mode 100644 index 0000000..67037ea --- /dev/null +++ b/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; +} diff --git a/src/models/index.ts b/src/models/index.ts index 92a8719..a24b64a 100644 --- a/src/models/index.ts +++ b/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"; diff --git a/src/user/getUserFriendsRequests.test.ts b/src/user/getUserFriendsRequests.test.ts new file mode 100644 index 0000000..b34e04a --- /dev/null +++ b/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(); + }); +}); diff --git a/src/user/getUserFriendsRequests.ts b/src/user/getUserFriendsRequests.ts new file mode 100644 index 0000000..3805141 --- /dev/null +++ b/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; + +/** + * 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 +): Promise => { + 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( + { 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; +}; diff --git a/src/user/index.ts b/src/user/index.ts index 67fffda..d5e63b0 100644 --- a/src/user/index.ts +++ b/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"; diff --git a/website/docs/api-docs/users.md b/website/docs/api-docs/users.md index 4d5e6c5..01ae2ec 100644 --- a/website/docs/api-docs/users.md +++ b/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