feat: adds getByPositionId (MetaMask#8602)

## Explanation

Expose GET /v1/traders/position/:positionId through SocialService as
fetchPositionById, returning a single Position by ID. Reuses the
existing Position type and PositionStruct validator; no new response
types needed.

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

- Related to
https://consensyssoftware.atlassian.net/jira/software/c/projects/TSA/boards/3368?assignee=5b58c0f5eda3e92ca73222ee&selectedIssue=TSA-461

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Additive change that introduces a new read-only API wrapper method
with schema validation and test coverage; minimal impact on existing
flows.
> 
> **Overview**
> Adds `SocialService.fetchPositionById` to retrieve a single `Position`
via `GET /v1/traders/position/:positionId`, including URL-encoding,
caching via `fetchQuery`, and response validation with the existing
`PositionStruct`.
> 
> Exposes the method through messenger action types/exports, introduces
`FetchPositionByIdOptions` plus new error messages, and adds unit tests
+ changelog entry for the new endpoint wrapper.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
495c91e. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joaosantos15

packages/social-controllers/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `SocialService.fetchPositionById` method exposing `GET /v1/traders/position/:positionId`, returning a single `Position` by ID ([#8602](https://github.com/MetaMask/core/pull/8602))
+
 ## [2.1.0]
 
 ### Added

packages/social-controllers/src/SocialService-method-action-types.ts

@@ -82,6 +82,20 @@ export type SocialServiceFetchFollowersAction = {
   handler: SocialService['fetchFollowers'];
 };
 
+/**
+ * Fetches a single position by its unique ID.
+ *
+ * Calls `GET ${baseUrl}/traders/position/${positionId}`.
+ *
+ * @param options - Options bag.
+ * @param options.positionId - Unique position ID (UUID).
+ * @returns The position.
+ */
+export type SocialServiceFetchPositionByIdAction = {
+  type: `SocialService:fetchPositionById`;
+  handler: SocialService['fetchPositionById'];
+};
+
 /**
  * Fetches the list of traders the current user is following.
  *
@@ -136,6 +150,7 @@ export type SocialServiceMethodActions =
   | SocialServiceFetchOpenPositionsAction
   | SocialServiceFetchClosedPositionsAction
   | SocialServiceFetchFollowersAction
+  | SocialServiceFetchPositionByIdAction
   | SocialServiceFetchFollowingAction
   | SocialServiceFollowAction
   | SocialServiceUnfollowAction;

packages/social-controllers/src/SocialService.test.ts

@@ -628,6 +628,85 @@ describe('SocialService', () => {
     });
   });
 
+  describe('fetchPositionById', () => {
+    it('fetches position from correct endpoint', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockPosition),
+      });
+
+      const service = createService();
+      const result = await service.fetchPositionById({
+        positionId: 'position-1',
+      });
+
+      expect(result).toStrictEqual(mockPosition);
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${V1_URL}/traders/position/position-1`,
+        { headers: { Authorization: `Bearer ${MOCK_TOKEN}` } },
+      );
+    });
+
+    it('encodes the positionId in the URL', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockPosition),
+      });
+
+      const service = createService();
+      await service.fetchPositionById({ positionId: 'pos/with/slashes' });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${V1_URL}/traders/position/pos%2Fwith%2Fslashes`,
+        { headers: { Authorization: `Bearer ${MOCK_TOKEN}` } },
+      );
+    });
+
+    it('throws HttpError on non-ok response', async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 404 });
+
+      const service = createService();
+
+      await expect(
+        service.fetchPositionById({ positionId: 'position-1' }),
+      ).rejects.toThrow(
+        `${SocialServiceErrorMessage.FETCH_POSITION_BY_ID_FAILED}: 404`,
+      );
+    });
+
+    it('throws when response schema is invalid', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ positionId: 123 }),
+      });
+
+      const service = createService();
+
+      await expect(
+        service.fetchPositionById({ positionId: 'position-1' }),
+      ).rejects.toThrow(
+        SocialServiceErrorMessage.FETCH_POSITION_BY_ID_INVALID_RESPONSE,
+      );
+    });
+
+    it('returns cached result on repeated calls with same positionId', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockPosition),
+      });
+
+      const service = createService();
+      await service.fetchPositionById({ positionId: 'position-1' });
+      await service.fetchPositionById({ positionId: 'position-1' });
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('fetchFollowing', () => {
     const mockFollowingResponse = {
       following: [mockProfileSummary],

packages/social-controllers/src/SocialService.ts

@@ -24,13 +24,15 @@ import { serviceName, SocialServiceErrorMessage } from './social-constants';
 import type {
   FetchFollowersOptions,
   FetchLeaderboardOptions,
+  FetchPositionByIdOptions,
   FetchPositionsOptions,
   FetchTraderProfileOptions,
   FollowersResponse,
   FollowingResponse,
   FollowOptions,
   FollowResponse,
   LeaderboardResponse,
+  Position,
   PositionsResponse,
   TraderProfileResponse,
   UnfollowOptions,
@@ -174,6 +176,7 @@ const MESSENGER_EXPOSED_METHODS = [
   'fetchClosedPositions',
   'fetchFollowers',
   'fetchFollowing',
+  'fetchPositionById',
   'follow',
   'unfollow',
 ] as const;
@@ -422,6 +425,43 @@ export class SocialService extends BaseDataService<
     return followersResponse;
   }
 
+  /**
+   * Fetches a single position by its unique ID.
+   *
+   * Calls `GET ${baseUrl}/traders/position/${positionId}`.
+   *
+   * @param options - Options bag.
+   * @param options.positionId - Unique position ID (UUID).
+   * @returns The position.
+   */
+  async fetchPositionById(
+    options: FetchPositionByIdOptions,
+  ): Promise<Position> {
+    const { positionId } = options;
+
+    const positionResponse = await this.fetchQuery({
+      queryKey: [`${this.name}:fetchPositionById`, positionId],
+      queryFn: async () => {
+        const url = `${this.#v1Url}/traders/position/${encodeURIComponent(positionId)}`;
+        const authHeaders = await this.#getAuthHeaders();
+        const response = await fetch(url, { headers: authHeaders });
+        SocialService.#throwIfNotOk(
+          response,
+          SocialServiceErrorMessage.FETCH_POSITION_BY_ID_FAILED,
+        );
+        const positionData = await response.json();
+        if (!is(positionData, PositionStruct)) {
+          throw new Error(
+            SocialServiceErrorMessage.FETCH_POSITION_BY_ID_INVALID_RESPONSE,
+          );
+        }
+        return positionData as Position;
+      },
+    });
+
+    return positionResponse;
+  }
+
   /**
    * Fetches the list of traders the current user is following.
    *

packages/social-controllers/src/index.ts

@@ -31,6 +31,7 @@ export type {
   SocialServiceFetchFollowingAction,
   SocialServiceFetchLeaderboardAction,
   SocialServiceFetchOpenPositionsAction,
+  SocialServiceFetchPositionByIdAction,
   SocialServiceFetchTraderProfileAction,
   SocialServiceFollowAction,
   SocialServiceUnfollowAction,
@@ -40,6 +41,7 @@ export { TradeStruct } from './social-types';
 export type {
   FetchFollowersOptions,
   FetchLeaderboardOptions,
+  FetchPositionByIdOptions,
   FetchPositionsOptions,
   FetchTraderProfileOptions,
   FollowersResponse,

packages/social-controllers/src/social-constants.ts

@@ -27,4 +27,7 @@ export const SocialServiceErrorMessage = {
   UNFOLLOW_FAILED: 'SocialService: Unfollow request failed',
   UNFOLLOW_INVALID_RESPONSE:
     'SocialService: Unfollow returned invalid response',
+  FETCH_POSITION_BY_ID_FAILED: 'SocialService: Position request failed',
+  FETCH_POSITION_BY_ID_INVALID_RESPONSE:
+    'SocialService: Position returned invalid response',
 } as const;

packages/social-controllers/src/social-types.ts

@@ -242,6 +242,11 @@ export type FetchFollowersOptions = {
   addressOrId: string;
 };
 
+export type FetchPositionByIdOptions = {
+  /** Unique position ID (UUID). */
+  positionId: string;
+};
+
 export type FollowOptions = {
   /** Array of wallet addresses or profile IDs to follow. */
   targets: string[];