feat(user): add getUserBlockedAccountIds function to retrieve blocked users ids

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

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;
+}

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

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();
+  });
+});

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<AllCallOptions, "limit" | "offset">;
+
+/**
+ * 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<GetUserBlockedAccountIdsOptions>
+): Promise<GetUserBlockedAccountIdsResponse> => {
+  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<GetUserBlockedAccountIdsResponse>(
+    { 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;
+};

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

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.