ref(seer): Type return as ResolvedViewerContext and add tests

Address review feedback: use TypedDict for the resolved context wire
format instead of dict[str, Any], and add tests covering all branches
of _resolve_viewer_context.

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

Author: gricha

src/sentry/seer/signed_seer_api.py

@@ -24,6 +24,20 @@ class SeerViewerContext(TypedDict, total=False):
     user_id: int | None
 
 
+class _SeerTokenPayload(TypedDict):
+    kind: str
+    scopes: list[str]
+
+
+class ResolvedViewerContext(TypedDict, total=False):
+    """Wire format for the X-Viewer-Context header sent to Seer."""
+
+    organization_id: int
+    user_id: int | None
+    actor_type: str
+    token: _SeerTokenPayload
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -50,7 +64,7 @@ class SeerViewerContext(TypedDict, total=False):
 
 def _resolve_viewer_context(
     explicit: SeerViewerContext | None,
-) -> dict[str, Any] | None:
+) -> ResolvedViewerContext | None:
     """Build the viewer context payload for Seer requests.
 
     Uses the contextvar as the base. If an explicit SeerViewerContext was
@@ -60,15 +74,17 @@ def _resolve_viewer_context(
     if vc is None and explicit is None:
         return None
 
-    result: dict[str, Any] = {}
+    result = ResolvedViewerContext()
     if vc is not None:
         if vc.organization_id is not None:
             result["organization_id"] = vc.organization_id
         if vc.user_id is not None:
             result["user_id"] = vc.user_id
         result["actor_type"] = vc.actor_type.value
         if vc.token is not None:
-            result["token"] = {"kind": vc.token.kind, "scopes": list(vc.token.get_scopes())}
+            result["token"] = _SeerTokenPayload(
+                kind=vc.token.kind, scopes=list(vc.token.get_scopes())
+            )
 
     if explicit:
         has_mismatch = False
@@ -81,7 +97,7 @@ def _resolve_viewer_context(
                 )
                 has_mismatch = True
             if val is not None:
-                result[field] = val
+                result[field] = val  # type: ignore[literal-required]
         if has_mismatch:
             result.pop("token", None)
 

tests/sentry/seer/test_signed_seer_api.py

@@ -3,7 +3,13 @@
 import pytest
 from django.test import override_settings
 
-from sentry.seer.signed_seer_api import make_signed_seer_api_request
+from sentry.auth.services.auth import AuthenticatedToken
+from sentry.seer.signed_seer_api import (
+    SeerViewerContext,
+    _resolve_viewer_context,
+    make_signed_seer_api_request,
+)
+from sentry.viewer_context import ActorType, ViewerContext, viewer_context_scope
 
 REQUEST_BODY = b'{"b": 12, "thing": "thing"}'
 PATH = "/v0/some/url"
@@ -111,3 +117,78 @@ def test_times_request(mock_metrics_timer: MagicMock, path: str) -> None:
             "endpoint": PATH,
         },
     )
+
+
+class TestResolveViewerContext:
+    def test_both_none(self) -> None:
+        assert _resolve_viewer_context(None) is None
+
+    def test_contextvar_only(self) -> None:
+        ctx = ViewerContext(organization_id=42, user_id=7, actor_type=ActorType.USER)
+        with viewer_context_scope(ctx):
+            result = _resolve_viewer_context(None)
+
+        assert result is not None
+        assert result["organization_id"] == 42
+        assert result["user_id"] == 7
+        assert result["actor_type"] == "user"
+
+    def test_explicit_only(self) -> None:
+        result = _resolve_viewer_context(SeerViewerContext(organization_id=99, user_id=5))
+        assert result is not None
+        assert result["organization_id"] == 99
+        assert result["user_id"] == 5
+
+    def test_contextvar_with_token(self) -> None:
+        token = AuthenticatedToken(
+            kind="api_token",
+            scopes=["org:read", "project:write"],
+            allowed_origins=[],
+        )
+        ctx = ViewerContext(organization_id=42, user_id=7, actor_type=ActorType.USER, token=token)
+        with viewer_context_scope(ctx):
+            result = _resolve_viewer_context(None)
+
+        assert result is not None
+        assert result["token"]["kind"] == "api_token"
+        assert set(result["token"]["scopes"]) == {"org:read", "project:write"}
+
+    def test_explicit_overrides_contextvar(self) -> None:
+        ctx = ViewerContext(organization_id=42, user_id=7, actor_type=ActorType.USER)
+        with viewer_context_scope(ctx):
+            result = _resolve_viewer_context(SeerViewerContext(organization_id=42, user_id=99))
+
+        assert result is not None
+        assert result["organization_id"] == 42
+        assert result["user_id"] == 99
+        assert result["actor_type"] == "user"
+
+    @patch("sentry.seer.signed_seer_api.logger")
+    def test_mismatch_warns_and_strips_token(self, mock_logger: MagicMock) -> None:
+        token = AuthenticatedToken(
+            kind="api_token",
+            scopes=["org:read"],
+            allowed_origins=[],
+        )
+        ctx = ViewerContext(organization_id=42, user_id=7, actor_type=ActorType.USER, token=token)
+        with viewer_context_scope(ctx):
+            result = _resolve_viewer_context(SeerViewerContext(organization_id=999))
+
+        assert result is not None
+        assert result["organization_id"] == 999
+        assert "token" not in result
+        mock_logger.warning.assert_called_once()
+        assert mock_logger.warning.call_args[0][0] == "seer.viewer_context_mismatch"
+
+    def test_no_mismatch_keeps_token(self) -> None:
+        token = AuthenticatedToken(
+            kind="api_token",
+            scopes=["org:read"],
+            allowed_origins=[],
+        )
+        ctx = ViewerContext(organization_id=42, user_id=7, actor_type=ActorType.USER, token=token)
+        with viewer_context_scope(ctx):
+            result = _resolve_viewer_context(SeerViewerContext(organization_id=42, user_id=7))
+
+        assert result is not None
+        assert "token" in result