Refine nexus bridge typing

Editor/nexus_bridge/_transport.py

@@ -5,7 +5,8 @@
 import os
 import sys
 import urllib.request
-from typing import Any
+
+from ._types import JsonObject, JsonRpcError, JsonRpcRequest, JsonRpcResponse
 
 DEFAULT_PORT: int = 8081
 
@@ -44,8 +45,8 @@ def _read_timeout() -> float:
 UNITY_TIMEOUT_SECONDS: float = _read_timeout()
 
 
-def call_unity(method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
-    payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method, "params": params or {}, "id": 1}
+def call_unity(method: str, params: JsonObject | None = None) -> JsonRpcResponse:
+    payload: JsonRpcRequest = {"jsonrpc": "2.0", "method": method, "params": params or {}, "id": 1}
     data: bytes = json.dumps(payload).encode("utf-8")
     req: urllib.request.Request = urllib.request.Request(
         UNITY_URL,
@@ -56,4 +57,8 @@ def call_unity(method: str, params: dict[str, Any] | None = None) -> dict[str, A
         with urllib.request.urlopen(req, timeout=UNITY_TIMEOUT_SECONDS) as response:
             return json.loads(response.read().decode("utf-8"))
     except Exception as error:
-        return {"error": {"code": -32000, "message": f"Unity Server unreachable. Error: {error}"}}
+        error_payload: JsonRpcError = {
+            "code": -32000,
+            "message": f"Unity Server unreachable. Error: {error}",
+        }
+        return {"error": error_payload}

Editor/nexus_bridge/_types.py

@@ -0,0 +1,76 @@
+"""Private type definitions for the NexusUnity Python bridge."""
+from __future__ import annotations
+
+from typing import Any, TypeAlias, TypedDict
+
+JsonObject: TypeAlias = dict[str, Any]
+
+
+class JsonRpcError(TypedDict):
+    code: int
+    message: str
+
+
+class JsonRpcRequest(TypedDict):
+    jsonrpc: str
+    method: str
+    params: JsonObject
+    id: int
+
+
+class ToolDefinition(TypedDict):
+    name: str
+    description: str
+    inputSchema: JsonObject
+
+
+class ResourceDefinition(TypedDict):
+    uri: str
+    name: str
+    mimeType: str
+
+
+class JsonRpcResponse(TypedDict, total=False):
+    result: JsonObject
+    error: JsonRpcError
+
+
+class TransformArguments(TypedDict, total=False):
+    instance_id: int
+    position: JsonObject
+    rotation: JsonObject
+    scale: JsonObject
+    eulerAngles: JsonObject
+    localScale: JsonObject
+
+
+class WriteFileSpec(TypedDict):
+    path: str
+    content: str
+
+
+class WriteError(TypedDict):
+    path: str
+    error: JsonRpcError
+
+
+class WaitResultPayload(TypedDict):
+    status: str
+    time_waited_seconds: float
+
+
+class TestResultsPayload(WaitResultPayload, total=False):
+    timestamp_utc: str
+    message: str
+    result_path: str
+    trigger: JsonObject
+
+
+class WriteAndCompileSuccessPayload(WaitResultPayload):
+    compiler_errors: list[JsonObject]
+
+
+class WriteAndCompileFailurePayload(TypedDict):
+    status: str
+    message: str
+    errors: list[WriteError]