Feat/tsa 317 social service (#8335)

## Explanation

Adds SocialService — a stateless data service that wraps all social-api
endpoints with TypeScript types and superstruct response validation.
This is the data layer that a future [SocialController
(TSA-318)](https://consensyssoftware.atlassian.net/browse/TSA-318) will
consume.

We intentionally shipped the service without the controller so callers
can weigh in on what state shape and messenger actions they actually
need before we wire up BaseController. The service stands on its own and
can be used directly for testing integration with the social-api once
it's deployed.

See CHANGELOG.md for the full list of additions.

<!--
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
-->

## 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]
> **Medium Risk**
> Introduces new networking and persisted state logic (via
`BaseDataService`/`BaseController`) for social-api interactions, which
could impact consumers if schemas/endpoints differ or caching semantics
are wrong. Scoped to a new package but touches request construction,
response validation, and follow/unfollow state updates.
> 
> **Overview**
> Adds an initial implementation of `@metamask/social-controllers`
focused on social trading data and state.
> 
> Introduces `SocialService` (a `BaseDataService`) that wraps social-api
endpoints (`leaderboard`, trader profile, open/closed positions,
followers/following, follow/unfollow) with `superstruct` response
validation, consistent `HttpError` handling, and query caching
(including special-casing open-positions cache keys and forcing fresh
fetches for follow/following mutations).
> 
> Adds `SocialController` (a `BaseController`) that persists UI-facing
state for `leaderboardEntries` and `followingAddresses`, exposing
messenger actions to refresh the leaderboard, follow/unfollow traders
(with address dedupe), and sync the following list. Package exports are
updated accordingly, with comprehensive Jest coverage, new dependencies,
TS project references, and an updated changelog.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
08282b0. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: António Regadas <apregadas@gmail.com>
Co-authored-by: Antonio Regadas <antonio.regadas@consensys.net>

Author: 3 people

packages/social-controllers/CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release ([#8321](https://github.com/MetaMask/core/pull/8321))
+- Initial release ([#8321](https://github.com/MetaMask/core/pull/8321), [#8335](https://github.com/MetaMask/core/pull/8335), [#8337](https://github.com/MetaMask/core/pull/8337))
+  - Add `SocialService` data service wrapping social-api endpoints with superstruct response validation
+    - Add methods `fetchLeaderboard`, `fetchTraderProfile`, `fetchOpenPositions`, `fetchClosedPositions`, `fetchFollowers`, `fetchFollowing`, `follow`, `unfollow`
+  - Add `SocialController` extending `BaseController` with messenger actions for state management
+    - `updateLeaderboard` — fetches leaderboard and persists entries to state
+    - `followTrader` — follows traders and updates following addresses in state
+    - `unfollowTrader` — unfollows traders and removes addresses from state
+    - `updateFollowing` — fetches following list and replaces addresses in state
 
 [Unreleased]: https://github.com/MetaMask/core/

packages/social-controllers/package.json

@@ -47,6 +47,13 @@
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
+  "dependencies": {
+    "@metamask/base-controller": "^9.0.1",
+    "@metamask/base-data-service": "^0.1.1",
+    "@metamask/controller-utils": "^11.20.0",
+    "@metamask/messenger": "^1.1.0",
+    "@metamask/superstruct": "^3.1.0"
+  },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.4.4",
     "@ts-bridge/cli": "^0.6.4",

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

@@ -0,0 +1,65 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+
+import type { SocialController } from './SocialController';
+
+/**
+ * Fetches the leaderboard and persists the entries to state.
+ *
+ * @param options - Optional leaderboard query parameters.
+ * @returns The leaderboard response from the social-api.
+ */
+export type SocialControllerUpdateLeaderboardAction = {
+  type: `SocialController:updateLeaderboard`;
+  handler: SocialController['updateLeaderboard'];
+};
+
+/**
+ * Follows one or more traders and updates the following list in state.
+ *
+ * @param options - Options bag.
+ * @param options.addressOrUid - Wallet address or Clicker profile ID of the current user.
+ * @param options.targets - Addresses or profile IDs to follow.
+ * @returns The follow response with confirmed follows.
+ */
+export type SocialControllerFollowTraderAction = {
+  type: `SocialController:followTrader`;
+  handler: SocialController['followTrader'];
+};
+
+/**
+ * Unfollows one or more traders and updates the following list in state.
+ *
+ * @param options - Options bag.
+ * @param options.addressOrUid - Wallet address or Clicker profile ID of the current user.
+ * @param options.targets - Addresses or profile IDs to unfollow.
+ * @returns The unfollow response with confirmed unfollows.
+ */
+export type SocialControllerUnfollowTraderAction = {
+  type: `SocialController:unfollowTrader`;
+  handler: SocialController['unfollowTrader'];
+};
+
+/**
+ * Fetches the list of traders the current user follows and replaces
+ * the following addresses in state.
+ *
+ * @param options - Options bag.
+ * @param options.addressOrUid - Wallet address or Clicker profile ID of the current user.
+ * @returns The following response.
+ */
+export type SocialControllerUpdateFollowingAction = {
+  type: `SocialController:updateFollowing`;
+  handler: SocialController['updateFollowing'];
+};
+
+/**
+ * Union of all SocialController action types.
+ */
+export type SocialControllerMethodActions =
+  | SocialControllerUpdateLeaderboardAction
+  | SocialControllerFollowTraderAction
+  | SocialControllerUnfollowTraderAction
+  | SocialControllerUpdateFollowingAction;