typing(rpc): Richer annotation for the return type of list_surveys

.changes/unreleased/Typing-20250103-101152.yaml

@@ -0,0 +1,5 @@
+kind: Typing
+body: Richer annotation for the return type of `list_surveys`
+time: 2025-01-03T10:11:52.478901-06:00
+custom:
+    Issue: "1245"

src/citric/client.py

@@ -1493,7 +1493,7 @@ def list_surveys(
         username: str | None = None,
         *,
         survey_group_id: int | None = None,
-    ) -> list[dict[str, t.Any]]:
+    ) -> list[types.SurveyListElement]:
         """Get all surveys or only those owned by a user.
 
         Calls :rpc_method:`list_surveys`.

src/citric/types.py

@@ -409,6 +409,31 @@ class SetQuotaPropertiesResult(t.TypedDict):
     """The quota properties."""
 
 
+class SurveyListElement(t.TypedDict, total=False):
+    """List surveys result."""
+
+    sid: int
+    """The survey ID."""
+
+    gsid: int
+    """The survey group ID.
+
+    .. minlimesurveyattribute:: 6.9.0
+    """
+
+    surveyls_title: str
+    """The survey title."""
+
+    startdate: str
+    """The survey start date."""
+
+    expires: str
+    """The survey expiration date."""
+
+    active: YesNo
+    """Whether the survey is active."""
+
+
 class SurveyProperties(t.TypedDict, total=False):
     """Survey properties result."""