fix(sdk): improve API response typing and error handling (#532)

* fix(sdk): improve API response typing and error handling in Python and TS SDKs

- request_binary: parse JSON error body on failure for detailed error messages
- flush(): use FlagResponse type instead of untyped dict/unsafe cast
- patch_message_meta/patch_configs: remove type:ignore and unsafe as casts
- project configs: add ProjectConfig Pydantic model and Zod schema
- download_to_sandbox: add DownloadToSandboxResp model instead of ad-hoc extraction

* fix(sdk-py): remove unused Any import in project.py

* fix(sdk): add type guards for error field and flush response validation

- Add isinstance/typeof checks for error field in Python and TS error parsing
- Add isinstance guard before FlagResponse.model_validate in flush()

* fix(sdk): address code review issues in response handling and type safety

- Add response guard in TS flush() to handle non-JSON responses gracefully
- Replace unsafe `as` cast with type guard for payload.error in TS client
- Fix TS getMessages timeDesc default to null to match Python SDK behavior
- Initialize parsed variable in Python sync client to match async client

Author: GenerQAQ

src/client/acontext-py/src/acontext/async_client.py

@@ -197,7 +197,8 @@ def _handle_response(response: httpx.Response, *, unwrap: bool) -> Any:
             error: str | None = None
             if payload and isinstance(payload, Mapping):
                 message = str(payload.get("msg") or payload.get("message") or message)
-                error = payload.get("error")
+                error_val = payload.get("error")
+                error = error_val if isinstance(error_val, str) else None
                 try:
                     code_val = payload.get("code")
                     if isinstance(code_val, int):
@@ -269,9 +270,31 @@ async def request_binary(
             raise TransportError(str(exc)) from exc
 
         if response.status_code >= 400:
+            # Try to parse JSON error body for detailed error info
+            # (API returns JSON errors even for binary endpoints)
+            content_type = response.headers.get("content-type", "")
+            message = response.reason_phrase
+            code: int | None = None
+            error: str | None = None
+            payload: Mapping[str, Any] | None = None
+            if "application/json" in content_type:
+                try:
+                    parsed = response.json()
+                    if isinstance(parsed, Mapping):
+                        payload = parsed
+                        message = str(parsed.get("msg") or parsed.get("message") or message)
+                        error = parsed.get("error")
+                        code_val = parsed.get("code")
+                        if isinstance(code_val, int):
+                            code = code_val
+                except ValueError:
+                    pass
             raise APIError(
                 status_code=response.status_code,
-                message=response.reason_phrase,
+                code=code,
+                message=message,
+                error=error,
+                payload=payload,
             )
 
         # Return raw bytes without decoding

src/client/acontext-py/src/acontext/client.py

@@ -180,7 +180,7 @@ def request(
     def _handle_response(response: httpx.Response, *, unwrap: bool) -> Any:
         content_type = response.headers.get("content-type", "")
 
-        parsed: Mapping[str, Any] | None
+        parsed: Mapping[str, Any] | None = None
         if "application/json" in content_type:
             try:
                 parsed = response.json()  # dict
@@ -196,7 +196,8 @@ def _handle_response(response: httpx.Response, *, unwrap: bool) -> Any:
             error: str | None = None
             if payload and isinstance(payload, Mapping):
                 message = str(payload.get("msg") or payload.get("message") or message)
-                error = payload.get("error")
+                error_val = payload.get("error")
+                error = error_val if isinstance(error_val, str) else None
                 try:
                     code_val = payload.get("code")
                     if isinstance(code_val, int):
@@ -268,9 +269,31 @@ def request_binary(
             raise TransportError(str(exc)) from exc
 
         if response.status_code >= 400:
+            # Try to parse JSON error body for detailed error info
+            # (API returns JSON errors even for binary endpoints)
+            content_type = response.headers.get("content-type", "")
+            message = response.reason_phrase
+            code: int | None = None
+            error: str | None = None
+            payload: Mapping[str, Any] | None = None
+            if "application/json" in content_type:
+                try:
+                    parsed = response.json()
+                    if isinstance(parsed, Mapping):
+                        payload = parsed
+                        message = str(parsed.get("msg") or parsed.get("message") or message)
+                        error = parsed.get("error")
+                        code_val = parsed.get("code")
+                        if isinstance(code_val, int):
+                            code = code_val
+                except ValueError:
+                    pass
             raise APIError(
                 status_code=response.status_code,
-                message=response.reason_phrase,
+                code=code,
+                message=message,
+                error=error,
+                payload=payload,
             )
 
         # Return raw bytes without decoding

src/client/acontext-py/src/acontext/resources/async_disks.py

@@ -13,6 +13,7 @@
 from ..types.disk import (
     Artifact,
     Disk,
+    DownloadToSandboxResp,
     GetArtifactResp,
     ListArtifactsResp,
     ListDisksOutput,
@@ -332,7 +333,7 @@ async def download_to_sandbox(
             f"/disk/{disk_id}/artifact/download_to_sandbox",
             json_data=payload,
         )
-        return bool(data.get("success", False))
+        return DownloadToSandboxResp.model_validate(data).success
 
     async def upload_from_sandbox(
         self,

src/client/acontext-py/src/acontext/resources/async_project.py

@@ -5,32 +5,37 @@
 from typing import Any
 
 from ..client_types import AsyncRequesterProtocol
+from ..types.project import ProjectConfig
 
 
 class AsyncProjectAPI:
     def __init__(self, requester: AsyncRequesterProtocol) -> None:
         self._requester = requester
 
-    async def get_configs(self) -> dict[str, Any]:
+    async def get_configs(self) -> ProjectConfig:
         """Get the project-level configuration.
 
         Returns:
-            Dictionary containing the current project configuration.
+            ProjectConfig containing the current project configuration.
         """
         data = await self._requester.request("GET", "/project/configs")
-        return data if isinstance(data, dict) else {}
+        if isinstance(data, dict):
+            return ProjectConfig.model_validate(data)
+        return ProjectConfig()
 
-    async def update_configs(self, configs: dict[str, Any]) -> dict[str, Any]:
+    async def update_configs(self, configs: dict[str, Any]) -> ProjectConfig:
         """Update the project-level configuration by merging keys.
         Keys with None/null values are deleted (reset to default).
 
         Args:
             configs: Dictionary of configuration keys to merge.
 
         Returns:
-            Dictionary containing the updated project configuration.
+            ProjectConfig containing the updated project configuration.
         """
         data = await self._requester.request(
             "PATCH", "/project/configs", json_data=configs
         )
-        return data if isinstance(data, dict) else {}
+        if isinstance(data, dict):
+            return ProjectConfig.model_validate(data)
+        return ProjectConfig()

src/client/acontext-py/src/acontext/resources/async_sessions.py

@@ -8,6 +8,7 @@
 from .._utils import build_params, validate_edit_strategies
 from ..client_types import AsyncRequesterProtocol
 from ..messages import AcontextMessage
+from ..types.common import FlagResponse
 from ..types.session import (
     EditStrategy,
     CopySessionResult,
@@ -427,17 +428,19 @@ async def get_messages(
         )
         return GetMessagesOutput.model_validate(data)
 
-    async def flush(self, session_id: str) -> dict[str, Any]:
+    async def flush(self, session_id: str) -> FlagResponse:
         """Flush the session buffer for a given session.
 
         Args:
             session_id: The UUID of the session.
 
         Returns:
-            Dictionary containing status and errmsg fields.
+            FlagResponse containing status and errmsg fields.
         """
         data = await self._requester.request("POST", f"/session/{session_id}/flush")
-        return data  # type: ignore
+        if isinstance(data, dict):
+            return FlagResponse.model_validate(data)
+        return FlagResponse(status=0, errmsg="")
 
     async def get_token_counts(self, session_id: str) -> TokenCounts:
         """Get total token counts for all text and tool-call parts in a session.
@@ -512,7 +515,9 @@ async def patch_message_meta(
             f"/session/{session_id}/messages/{message_id}/meta",
             json_data=payload,
         )
-        return data.get("meta", {})  # type: ignore
+        if isinstance(data, dict):
+            return data.get("meta", {})
+        return {}
 
     async def patch_configs(
         self,
@@ -551,7 +556,9 @@ async def patch_configs(
             f"/session/{session_id}/configs",
             json_data=payload,
         )
-        return data.get("configs", {})  # type: ignore
+        if isinstance(data, dict):
+            return data.get("configs", {})
+        return {}
 
     async def copy(self, session_id: str) -> CopySessionResult:
         """Copy (duplicate) a session with all its messages and tasks.

src/client/acontext-py/src/acontext/resources/disks.py

@@ -15,6 +15,7 @@
 from ..types.disk import (
     Artifact,
     Disk,
+    DownloadToSandboxResp,
     GetArtifactResp,
     ListArtifactsResp,
     ListDisksOutput,
@@ -332,7 +333,7 @@ def download_to_sandbox(
             f"/disk/{disk_id}/artifact/download_to_sandbox",
             json_data=payload,
         )
-        return bool(data.get("success", False))
+        return DownloadToSandboxResp.model_validate(data).success
 
     def upload_from_sandbox(
         self,

src/client/acontext-py/src/acontext/resources/project.py

@@ -5,32 +5,37 @@
 from typing import Any
 
 from ..client_types import RequesterProtocol
+from ..types.project import ProjectConfig
 
 
 class ProjectAPI:
     def __init__(self, requester: RequesterProtocol) -> None:
         self._requester = requester
 
-    def get_configs(self) -> dict[str, Any]:
+    def get_configs(self) -> ProjectConfig:
         """Get the project-level configuration.
 
         Returns:
-            Dictionary containing the current project configuration.
+            ProjectConfig containing the current project configuration.
         """
         data = self._requester.request("GET", "/project/configs")
-        return data if isinstance(data, dict) else {}
+        if isinstance(data, dict):
+            return ProjectConfig.model_validate(data)
+        return ProjectConfig()
 
-    def update_configs(self, configs: dict[str, Any]) -> dict[str, Any]:
+    def update_configs(self, configs: dict[str, Any]) -> ProjectConfig:
         """Update the project-level configuration by merging keys.
         Keys with None/null values are deleted (reset to default).
 
         Args:
             configs: Dictionary of configuration keys to merge.
 
         Returns:
-            Dictionary containing the updated project configuration.
+            ProjectConfig containing the updated project configuration.
         """
         data = self._requester.request(
             "PATCH", "/project/configs", json_data=configs
         )
-        return data if isinstance(data, dict) else {}
+        if isinstance(data, dict):
+            return ProjectConfig.model_validate(data)
+        return ProjectConfig()

src/client/acontext-py/src/acontext/resources/sessions.py

@@ -8,6 +8,7 @@
 from .._utils import build_params, validate_edit_strategies
 from ..client_types import RequesterProtocol
 from ..messages import AcontextMessage
+from ..types.common import FlagResponse
 from ..types.session import (
     EditStrategy,
     CopySessionResult,
@@ -427,17 +428,19 @@ def get_messages(
         )
         return GetMessagesOutput.model_validate(data)
 
-    def flush(self, session_id: str) -> dict[str, Any]:
+    def flush(self, session_id: str) -> FlagResponse:
         """Flush the session buffer for a given session.
 
         Args:
             session_id: The UUID of the session.
 
         Returns:
-            Dictionary containing status and errmsg fields.
+            FlagResponse containing status and errmsg fields.
         """
         data = self._requester.request("POST", f"/session/{session_id}/flush")
-        return data  # type: ignore
+        if isinstance(data, dict):
+            return FlagResponse.model_validate(data)
+        return FlagResponse(status=0, errmsg="")
 
     def get_token_counts(self, session_id: str) -> TokenCounts:
         """Get total token counts for all text and tool-call parts in a session.
@@ -506,7 +509,9 @@ def patch_message_meta(
             f"/session/{session_id}/messages/{message_id}/meta",
             json_data=payload,
         )
-        return data.get("meta", {})  # type: ignore
+        if isinstance(data, dict):
+            return data.get("meta", {})
+        return {}
 
     def patch_configs(
         self,
@@ -545,7 +550,9 @@ def patch_configs(
             f"/session/{session_id}/configs",
             json_data=payload,
         )
-        return data.get("configs", {})  # type: ignore
+        if isinstance(data, dict):
+            return data.get("configs", {})
+        return {}
 
     def copy(self, session_id: str) -> CopySessionResult:
         """Copy (duplicate) a session with all its messages and tasks.

src/client/acontext-py/src/acontext/types/__init__.py

@@ -4,6 +4,7 @@
 from .disk import (
     Artifact,
     Disk,
+    DownloadToSandboxResp,
     GetArtifactResp,
     ListArtifactsResp,
     ListDisksOutput,
@@ -44,6 +45,7 @@
     User,
     UserResourceCounts,
 )
+from .project import ProjectConfig
 from .learning_space import (
     LearningSpace,
     LearningSpaceSession,
@@ -58,6 +60,7 @@
     # Disk types
     "Artifact",
     "Disk",
+    "DownloadToSandboxResp",
     "GetArtifactResp",
     "ListArtifactsResp",
     "ListDisksOutput",
@@ -93,6 +96,8 @@
     "ListUsersOutput",
     "User",
     "UserResourceCounts",
+    # Project types
+    "ProjectConfig",
     # Learning space types
     "LearningSpace",
     "LearningSpaceSession",

src/client/acontext-py/src/acontext/types/disk.py

@@ -62,3 +62,9 @@ class UpdateArtifactResp(BaseModel):
     """Response model for updating an artifact."""
 
     artifact: Artifact = Field(..., description="Updated artifact information")
+
+
+class DownloadToSandboxResp(BaseModel):
+    """Response model for downloading an artifact to a sandbox."""
+
+    success: bool = Field(..., description="Whether the download was successful")