Feat/scope api (#119)

* feat: add api_me_scope to MultipassClient for me/scope endpoint

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: document api_me_scope response structure and add type assertion to test

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* style: use plain requests.Response in docstring for consistency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nicornk

libs/foundry-dev-tools/src/foundry_dev_tools/clients/multipass.py

@@ -95,6 +95,53 @@ def api_me(self, **kwargs) -> requests.Response:
             **kwargs,
         )
 
+    def api_me_scope(self, **kwargs) -> requests.Response:
+        """Gets the current user's scope.
+
+        Args:
+            **kwargs: gets passed to :py:meth:`APIClient.api_request`
+
+        Returns:
+            requests.Response:
+                The response JSON is a recursive scope structure with a ``type`` field.
+
+        .. code-block:: python
+
+           # User token:
+           {"type": "universal"}
+
+           # Scoped token (e.g. TPA with authorization_code grant):
+           {
+               "type": "union",
+               "scopes": [
+                   {
+                       "type": "intersection",
+                       "scopes": [
+                           {"type": "operation", "operations": ["api:read-data", ...]},
+                           {"type": "operation", "operations": ["api:read-data", ...]},
+                       ],
+                   },
+                   {
+                       "type": "intersection",
+                       "scopes": [
+                           {
+                               "type": "resource",
+                               "resourceIds": ["ri.multipass..organization.root"],
+                               "includeChildren": True,
+                           },
+                           {"type": "operation", "operations": ["organization:discover", ...]},
+                       ],
+                   },
+               ],
+           }
+
+        """
+        return self.api_request(
+            "GET",
+            "me/scope",
+            **kwargs,
+        )
+
     def search(
         self, query: str, principal_types: set[api_types.PrincipalTypes] | None = None, **kwargs
     ) -> Iterator[dict]:

tests/integration/clients/test_multipass.py

@@ -45,6 +45,17 @@ def _tear_down():
             raise
 
 
+def test_me_scope():
+    resp = TEST_SINGLETON.ctx.multipass.api_me_scope()
+
+    assert resp.status_code == 200
+
+    scope = resp.json()
+    assert isinstance(scope, dict)
+    assert "type" in scope
+    assert scope["type"] in ("universal", "union", "intersection", "operation", "resource")
+
+
 def test_organizations():
     user_info = TEST_SINGLETON.ctx.multipass.get_user_info()