Feature/add expands fields relations to get user by id v2 (#148)

* feat: add fields/relations passthrough to GET /api/v1|v2/users/{id}

Wires SerializerUtils::getExpand()/getFields()/getRelations() into both
by-ID user endpoints (matching the ParametrizedGetAll pattern already
used by list endpoints), and makes PrivateUserSerializer treat `groups`
as a gated relation (mirroring ApiScopeGroupSerializer) instead of
appending it unconditionally.

Unblocks ftn-docsnsklz PR #76 (SDS ftn-attendee-native-realtime-comms.md,
D38): attendee-networking-api's IDP user_updated consumer needs to fetch
exactly fields=public_profile_allow_chat_with_me,first_name,last_name,pic
without pulling the rest of the private profile.

v1 get() also migrated from manual try/catch to the shared
processRequest() wrapper for consistent error handling with getV2().

Also fixes an unrelated pre-existing bug in UserLoginTurnstileTest where
$testEmail/$testPassword being typed as non-nullable string caused a
TypeError before the test's own markTestSkipped() logic could run when
TEST_USER_EMAIL/TEST_USER_PASSWORD are unset.

9 new tests added to OAuth2UserApiTest; full suite green (180 tests,
0 failures, 7 legitimate skips).

* docs(plan): mark spec as VERIFIED

* chore: untrack plan file — plan docs are working artifacts, not committed

* fix: document v1 expand param and add v1 default-shape regression test

Address deep-review findings on PR #148:
- OA\Get annotation for GET /api/v1/users/{id} was missing the `expand`
  parameter even though get() already passed SerializerUtils::getExpand()
  into serialize() -- the capability was live but undocumented.
- v1 lacked a default-shape regression test symmetric with
  testGetUserByIdV2WithNoParamsReturnsSameShapeAsBefore, so the
  fields/relations passthrough's backward compatibility on v1 was only
  exercised incidentally.

Author: smarcet

app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php

@@ -20,6 +20,7 @@
 use App\Http\Exceptions\HTTP403ForbiddenException;
 use App\Http\Utils\HTMLCleaner;
 use App\ModelSerializers\SerializerRegistry;
+use App\ModelSerializers\SerializerUtils;
 use Auth\Repositories\IUserRepository;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request as LaravelRequest;
@@ -640,6 +641,27 @@ public function userInfo()
                 required: true,
                 schema: new OA\Schema(type: 'integer')
             ),
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expand relations: groups',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'fields',
+                description: 'Comma-separated list of scalar fields to return, e.g. first_name,last_name,pic,public_profile_allow_chat_with_me',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'relations',
+                description: 'Comma-separated list of relations to include (supported: groups)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
         ],
         responses: [
             new OA\Response(
@@ -663,22 +685,19 @@ public function userInfo()
     )]
     public function get($id)
     {
-        try {
+        return $this->processRequest(function () use ($id) {
             $user = $this->repository->getById(intval($id));
             if (is_null($user)) {
                 throw new EntityNotFoundException();
             }
-            return $this->ok(SerializerRegistry::getInstance()->getSerializer($user, SerializerRegistry::SerializerType_Private)->serialize());
-        } catch (ValidationException $ex1) {
-            Log::warning($ex1);
-            return $this->error412($ex1->getMessages());
-        } catch (EntityNotFoundException $ex2) {
-            Log::warning($ex2);
-            return $this->error404(['message' => $ex2->getMessage()]);
-        } catch (Exception $ex) {
-            Log::error($ex);
-            return $this->error500($ex);
-        }
+            return $this->ok(SerializerRegistry::getInstance()
+                ->getSerializer($user, SerializerRegistry::SerializerType_Private)
+                ->serialize(
+                    SerializerUtils::getExpand(),
+                    SerializerUtils::getFields(),
+                    SerializerUtils::getRelations()
+                ));
+        });
     }
 
     /**
@@ -716,6 +735,20 @@ public function get($id)
                 required: false,
                 schema: new OA\Schema(type: 'string')
             ),
+            new OA\Parameter(
+                name: 'fields',
+                description: 'Comma-separated list of scalar fields to return, e.g. first_name,last_name,pic,public_profile_allow_chat_with_me',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'relations',
+                description: 'Comma-separated list of relations to include (supported: groups)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
         ],
         responses: [
             new OA\Response(
@@ -747,7 +780,9 @@ public function getV2($id)
             return $this->ok(SerializerRegistry::getInstance()
                 ->getSerializer($user, SerializerRegistry::SerializerType_Private)
                 ->serialize(
-                    Request::input("expand", '')
+                    SerializerUtils::getExpand(),
+                    SerializerUtils::getFields(),
+                    SerializerUtils::getRelations()
                 ));
         });
     }

app/ModelSerializers/Auth/UserSerializer.php

@@ -46,6 +46,10 @@ final class PublicUserSerializer extends BaseUserSerializer
 final class PrivateUserSerializer extends BaseUserSerializer
 {
 
+    protected static $allowed_relations = [
+        'groups',
+    ];
+
     protected static $array_mappings = [
         'Email' => 'email:json_string',
         'Identifier' => 'identifier:json_string',
@@ -96,15 +100,19 @@ public function serialize($expand = null, array $fields = [], array $relations =
         $user = $this->object;
         if (!$user instanceof User) return [];
 
+        if (!count($relations)) $relations = $this->getAllowedRelations();
+
         $values = parent::serialize($expand, $fields, $relations, $params);
 
-        $groups = [];
-        foreach ($user->getGroups() as $group) {
-            if (!$group instanceof Group) continue;
-            $groups[] = $group->getSlug();
-        }
+        if (in_array('groups', $relations)) {
+            $groups = [];
+            foreach ($user->getGroups() as $group) {
+                if (!$group instanceof Group) continue;
+                $groups[] = $group->getSlug();
+            }
 
-        $values['groups'] = $groups;
+            $values['groups'] = $groups;
+        }
 
         if (!empty($expand)) {
             $exp_expand = explode(',', $expand);