Return UserRelation instead of UserCompact for friends API

[cl8n]

resolves #7637

[nanaya]

It looks like this will need to be coordinated with lazer.

[cl8n]

yep. I'll wait for review on this first to get the API decided

I also removed the statistics include from the users in this response because I don't think it made sense to use the auth'd user's default mode (friends.read doesn't imply knowledge of that)... but lazer does use that info currently. should I add it back and require identify scope too or something?

[peppy]

Fine to go ahead with this at your discretion (assuming this seems like a sane change - I think it does but haven't looked into it with too much thought).

Will coordinate the lazer side changes if/when this is merged.

[nanaya]

About statistics; identify scope is always implied. If anything, the check should be at default_mode function instead.

[nanaya]

static $userIncludes = [ ... ];

if (is_api_request()) {
  return json_collection(..., ..., [
    "target:mode({$currentMode})",
    ...array_map(..., $userIncludes),
  ]);
}

[nanaya]

Make its own relation and load that instead.

// in User model
public function relationFriends()
{
  return $this->relations()->friends()->withMutual();
}

// in this controller action
// the loaded reloaded data will be used regardless (in json for api, in current user default json for html)
$relations = $currentUser->relationFriends;
$relations->load(['target' => fn ($q) => $q->...]);

if (is_api...) {
    ...
}

$user = $relations->pluck('target');

// in Transformers etc
$user->relationFriends

[peppy]

@cl8n still willing to apply the review to this one?

[nanaya]

The main thing has been merged through a different PR. Feel free to open another PR for the documentation (or maybe wait for the documentation system update PR (#11433) first?).