diff --git a/README.md b/README.md index f89374f..d2c3a64 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. +- [`getUserBlockedAccountIds()`](https://psn-api.achievements.app/api-docs/users#getuserblockedaccountids) - Get a list + of `accountId` values corresponding to accounts blocked by the account the client is logged into. - [`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 diff --git a/src/models/get-user-blocked-account-ids-response.model.ts b/src/models/get-user-blocked-account-ids-response.model.ts new file mode 100644 index 0000000..374faeb --- /dev/null +++ b/src/models/get-user-blocked-account-ids-response.model.ts @@ -0,0 +1,7 @@ +export interface GetUserBlockedAccountIdsResponse { + /** A list of `accountId` values corresponding to accounts that have been blocked by the user. */ + blockList: string[]; + + nextOffset?: number; + previousOffset?: number; +} \ No newline at end of file diff --git a/src/models/index.ts b/src/models/index.ts index a24b64a..59eb182 100644 --- a/src/models/index.ts +++ b/src/models/index.ts @@ -3,6 +3,7 @@ export * from "./auth-tokens-response.model"; export * from "./authorization-payload.model"; export * from "./basic-presence-response.model"; export * from "./call-valid-headers.model"; +export * from "./get-user-blocked-account-ids-response.model"; export * from "./get-user-friends-account-ids-response.model"; export * from "./get-user-friends-requests-response.model"; export * from "./membership.model"; diff --git a/src/user/getUserBlockedAccountIds.test.ts b/src/user/getUserBlockedAccountIds.test.ts new file mode 100644 index 0000000..4cec116 --- /dev/null +++ b/src/user/getUserBlockedAccountIds.test.ts @@ -0,0 +1,70 @@ +import nock from "nock"; + +import type { + AuthorizationPayload, + GetUserBlockedAccountIdsResponse +} from "../models"; +import { getUserBlockedAccountIds } from "./getUserBlockedAccountIds"; +import { USER_BASE_URL } from "./USER_BASE_URL"; + +describe("Function: getUserBlockedAccountIds", () => { + afterEach(() => { + nock.cleanAll(); + }); + + it("is defined #sanity", () => { + // ASSERT + expect(getUserBlockedAccountIds).toBeDefined(); + }); + + it("retrieves the blocked account IDs for the authenticated user", async () => { + // ARRANGE + const mockAuthorization: AuthorizationPayload = { + accessToken: "mockAccessToken" + }; + + const mockResponse: GetUserBlockedAccountIdsResponse = { + blockList: ["750503368741351124", "2984038888603282554"], + nextOffset: 2, + previousOffset: 0 + }; + + const baseUrlObj = new URL(USER_BASE_URL); + const baseUrl = `${baseUrlObj.protocol}//${baseUrlObj.host}`; + const basePath = baseUrlObj.pathname; + + nock(baseUrl) + .get(`${basePath}/me/blocks`) + .query(true) + .reply(200, mockResponse); + + // ACT + const response = await getUserBlockedAccountIds(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/blocks") + .query(true) + .reply(200, mockResponse); + + // ASSERT + await expect(getUserBlockedAccountIds(mockAuthorization)).rejects.toThrow(); + }); +}); \ No newline at end of file diff --git a/src/user/getUserBlockedAccountIds.ts b/src/user/getUserBlockedAccountIds.ts new file mode 100644 index 0000000..6165972 --- /dev/null +++ b/src/user/getUserBlockedAccountIds.ts @@ -0,0 +1,38 @@ +import type { + AllCallOptions, + AuthorizationPayload, + GetUserBlockedAccountIdsResponse +} from "../models"; +import { buildRequestUrl } from "../utils/buildRequestUrl"; +import { call } from "../utils/call"; +import { USER_BASE_URL } from "./USER_BASE_URL"; + +type GetUserBlockedAccountIdsOptions = Pick; + +/** + * A call to this function will retrieve the list of blocked `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 getUserBlockedAccountIds = async ( + authorization: AuthorizationPayload, + options?: Partial +): Promise => { + const url = buildRequestUrl(USER_BASE_URL, "/:accountId/blocks", 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 blocked list, an error will be thrown. + if ((response as any)?.error) { + throw new Error((response as any)?.error?.message ?? "Unexpected Error"); + } + + return response; +}; \ No newline at end of file diff --git a/src/user/index.ts b/src/user/index.ts index d5e63b0..145c5ca 100644 --- a/src/user/index.ts +++ b/src/user/index.ts @@ -3,6 +3,7 @@ export * from "./getBasicPresence"; export * from "./getProfileFromAccountId"; export * from "./getProfileFromUserName"; export * from "./getProfileShareableLink"; +export * from "./getUserBlockedAccountIds"; export * from "./getUserFriendsAccountIds"; export * from "./getUserFriendsRequests"; export * from "./getUserPlayedGames"; diff --git a/website/docs/api-docs/users.md b/website/docs/api-docs/users.md index 01ae2ec..b74c2ac 100644 --- a/website/docs/api-docs/users.md +++ b/website/docs/api-docs/users.md @@ -217,6 +217,49 @@ These are the possible values that can be in the `options` object (the third par --- +## getUserBlockedAccountIds + +A call to this function will retrieve the list of blocked `accountId` values for the account the client is logged into. + +### Examples + +#### Get blocked account IDs + +```ts +import { getUserBlockedAccountIds } from "psn-api"; + +const response = await getUserBlockedAccountIds(authorization); +``` + +### Returns + +| Name | Type | Description | +| :--------------- | :--------- | :------------------------------------------------------------------------- | +| `blockList` | `string[]` | The `accountId` values of the users who have been blocked by your account. | +| `nextOffset` | `number` | The offset for the next page of results. | +| `previousOffset` | `number` | The offset for the previous page of results. | + +### 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 blocked accounts returned. | +| `offset` | `number` | Return blocked account data from this result onwards. | + +### Source + +[user/getUserBlockedAccountIds.ts](https://github.com/achievements-app/psn-api/blob/main/src/user/getUserBlockedAccountIds.ts) + +--- + ## 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.