chore: tighten typing across plus_api client

Adds typed containers for wire payloads, literal aliases for HTTP method
and log type, and Ffnal markers on resource constants. Updates
upstream returns in project_utils.py and deploy/main.py to match
the new contracts.

Author: greysonlalonde

lib/cli/src/crewai_cli/deploy/main.py

@@ -1,5 +1,6 @@
 from typing import Any
 
+from crewai_core.plus_api import CreateCrewPayload
 from rich.console import Console
 
 from crewai_cli import git
@@ -161,7 +162,7 @@ def _create_payload(
         self,
         env_vars: dict[str, str],
         remote_repo_url: str,
-    ) -> dict[str, Any]:
+    ) -> CreateCrewPayload:
         """
         Create the payload for crew creation.
 
@@ -172,6 +173,8 @@ def _create_payload(
         Returns:
             Dict[str, Any]: The payload for crew creation.
         """
+        if not self.project_name:
+            raise ValueError("project_name is required to create a deployment payload")
         return {
             "deploy": {
                 "name": self.project_name,

lib/crewai-core/src/crewai_core/plus_api.py

@@ -3,36 +3,161 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+from typing import Any, Final, Literal, TypedDict, cast
 from urllib.parse import urljoin
 
 import httpx
+from typing_extensions import NotRequired
 
 from crewai_core.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai_core.settings import Settings
 from crewai_core.version import get_crewai_version
 
 
+HttpMethod = Literal["GET", "POST", "PATCH", "DELETE"]
+
+
+class AvailableExport(TypedDict):
+    name: str
+
+
+class EnvVarEntry(TypedDict):
+    name: str
+    description: str
+    required: bool
+    default: str | None
+
+
+class ToolMetadata(TypedDict):
+    name: str
+    module: str
+    humanized_name: str
+    description: str
+    run_params_schema: dict[str, Any]
+    init_params_schema: dict[str, Any]
+    env_vars: list[EnvVarEntry]
+
+
+class ToolsMetadataPayload(TypedDict):
+    package: str
+    tools: list[ToolMetadata] | None
+
+
+class PublishToolPayload(TypedDict):
+    handle: str
+    public: bool
+    version: str
+    file: str
+    description: str | None
+    available_exports: list[AvailableExport] | None
+    tools_metadata: ToolsMetadataPayload | None
+
+
+class CrewDeploymentSpec(TypedDict):
+    name: str
+    repo_clone_url: str
+    env: dict[str, str]
+
+
+class CreateCrewPayload(TypedDict):
+    deploy: CrewDeploymentSpec
+
+
+class _WithUserIdentifier(TypedDict):
+    user_identifier: NotRequired[str]
+
+
+class LoginPayload(_WithUserIdentifier):
+    pass
+
+
+class TraceExecutionContext(TypedDict):
+    crew_fingerprint: str | None
+    crew_name: str | None
+    flow_name: str | None
+    crewai_version: str
+    privacy_level: str
+
+
+class TraceExecutionMetadata(TypedDict):
+    expected_duration_estimate: int
+    agent_count: int
+    task_count: int
+    flow_method_count: int
+    execution_started_at: str
+
+
+class TraceBatchInitPayload(_WithUserIdentifier):
+    trace_id: str
+    execution_type: str
+    execution_context: TraceExecutionContext
+    execution_metadata: TraceExecutionMetadata
+    ephemeral_trace_id: NotRequired[str]
+
+
+class TraceBatchMetadata(TypedDict):
+    events_count: int
+    batch_sequence: int
+    is_final_batch: bool
+
+
+class TraceEventsPayload(TypedDict):
+    events: list[dict[str, Any]]
+    batch_metadata: TraceBatchMetadata
+
+
+class TraceFinalizePayload(TypedDict):
+    status: Literal["completed"]
+    duration_ms: float | None
+    final_event_count: int
+
+
+class TraceFailedPayload(TypedDict):
+    status: Literal["failed"]
+    failure_reason: str
+
+
+Headers = TypedDict(
+    "Headers",
+    {
+        "Content-Type": str,
+        "User-Agent": str,
+        "X-Crewai-Version": str,
+        "Authorization": NotRequired[str],
+        "X-Crewai-Organization-Id": NotRequired[str],
+    },
+)
+
+
+class RequestKwargs(TypedDict):
+    headers: dict[str, str]
+    json: NotRequired[Any]
+    params: NotRequired[dict[str, str]]
+    timeout: NotRequired[float]
+
+
 class PlusAPI:
     """Client for working with the CrewAI+ API."""
 
-    TOOLS_RESOURCE = "/crewai_plus/api/v1/tools"
-    ORGANIZATIONS_RESOURCE = "/crewai_plus/api/v1/me/organizations"
-    CREWS_RESOURCE = "/crewai_plus/api/v1/crews"
-    AGENTS_RESOURCE = "/crewai_plus/api/v1/agents"
-    TRACING_RESOURCE = "/crewai_plus/api/v1/tracing"
-    EPHEMERAL_TRACING_RESOURCE = "/crewai_plus/api/v1/tracing/ephemeral"
-    INTEGRATIONS_RESOURCE = "/crewai_plus/api/v1/integrations"
+    TOOLS_RESOURCE: Final = "/crewai_plus/api/v1/tools"
+    ORGANIZATIONS_RESOURCE: Final = "/crewai_plus/api/v1/me/organizations"
+    CREWS_RESOURCE: Final = "/crewai_plus/api/v1/crews"
+    AGENTS_RESOURCE: Final = "/crewai_plus/api/v1/agents"
+    TRACING_RESOURCE: Final = "/crewai_plus/api/v1/tracing"
+    EPHEMERAL_TRACING_RESOURCE: Final = "/crewai_plus/api/v1/tracing/ephemeral"
+    INTEGRATIONS_RESOURCE: Final = "/crewai_plus/api/v1/integrations"
 
     def __init__(self, api_key: str | None = None) -> None:
+        version = get_crewai_version()
         self.api_key = api_key
-        self.headers = {
+        self.headers: Headers = {
             "Content-Type": "application/json",
-            "User-Agent": f"CrewAI-CLI/{get_crewai_version()}",
-            "X-Crewai-Version": get_crewai_version(),
+            "User-Agent": f"CrewAI-CLI/{version}",
+            "X-Crewai-Version": version,
         }
         if api_key:
             self.headers["Authorization"] = f"Bearer {api_key}"
+
         settings = Settings()
         if settings.org_uuid:
             self.headers["X-Crewai-Organization-Id"] = settings.org_uuid
@@ -44,17 +169,30 @@ def __init__(self, api_key: str | None = None) -> None:
         )
 
     def _make_request(
-        self, method: str, endpoint: str, **kwargs: Any
+        self,
+        method: HttpMethod,
+        endpoint: str,
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+        verify: bool = True,
     ) -> httpx.Response:
         url = urljoin(self.base_url, endpoint)
-        verify = kwargs.pop("verify", True)
+        request_kwargs: RequestKwargs = {"headers": cast(dict[str, str], self.headers)}
+        if json is not None:
+            request_kwargs["json"] = json
+        if params is not None:
+            request_kwargs["params"] = params
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
         with httpx.Client(trust_env=False, verify=verify) as client:
-            return client.request(method, url, headers=self.headers, **kwargs)
+            return client.request(method, url, **request_kwargs)
 
     def login_to_tool_repository(
         self, user_identifier: str | None = None
     ) -> httpx.Response:
-        payload = {}
+        payload: LoginPayload = {}
         if user_identifier:
             payload["user_identifier"] = user_identifier
         return self._make_request("POST", f"{self.TOOLS_RESOURCE}/login", json=payload)
@@ -65,7 +203,7 @@ def get_tool(self, handle: str) -> httpx.Response:
     async def get_agent(self, handle: str) -> httpx.Response:
         url = urljoin(self.base_url, f"{self.AGENTS_RESOURCE}/{handle}")
         async with httpx.AsyncClient() as client:
-            return await client.get(url, headers=self.headers)
+            return await client.get(url, headers=cast(dict[str, str], self.headers))
 
     def publish_tool(
         self,
@@ -74,10 +212,10 @@ def publish_tool(
         version: str,
         description: str | None,
         encoded_file: str,
-        available_exports: list[dict[str, Any]] | None = None,
-        tools_metadata: list[dict[str, Any]] | None = None,
+        available_exports: list[AvailableExport] | None = None,
+        tools_metadata: list[ToolMetadata] | None = None,
     ) -> httpx.Response:
-        params = {
+        params: PublishToolPayload = {
             "handle": handle,
             "public": is_public,
             "version": version,
@@ -129,13 +267,13 @@ def delete_crew_by_uuid(self, uuid: str) -> httpx.Response:
     def list_crews(self) -> httpx.Response:
         return self._make_request("GET", self.CREWS_RESOURCE)
 
-    def create_crew(self, payload: dict[str, Any]) -> httpx.Response:
+    def create_crew(self, payload: CreateCrewPayload) -> httpx.Response:
         return self._make_request("POST", self.CREWS_RESOURCE, json=payload)
 
     def get_organizations(self) -> httpx.Response:
         return self._make_request("GET", self.ORGANIZATIONS_RESOURCE)
 
-    def initialize_trace_batch(self, payload: dict[str, Any]) -> httpx.Response:
+    def initialize_trace_batch(self, payload: TraceBatchInitPayload) -> httpx.Response:
         return self._make_request(
             "POST",
             f"{self.TRACING_RESOURCE}/batches",
@@ -144,7 +282,7 @@ def initialize_trace_batch(self, payload: dict[str, Any]) -> httpx.Response:
         )
 
     def initialize_ephemeral_trace_batch(
-        self, payload: dict[str, Any]
+        self, payload: TraceBatchInitPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -153,7 +291,7 @@ def initialize_ephemeral_trace_batch(
         )
 
     def send_trace_events(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceEventsPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -163,7 +301,7 @@ def send_trace_events(
         )
 
     def send_ephemeral_trace_events(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceEventsPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -173,7 +311,7 @@ def send_ephemeral_trace_events(
         )
 
     def finalize_trace_batch(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceFinalizePayload
     ) -> httpx.Response:
         return self._make_request(
             "PATCH",
@@ -183,7 +321,7 @@ def finalize_trace_batch(
         )
 
     def finalize_ephemeral_trace_batch(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceFinalizePayload
     ) -> httpx.Response:
         return self._make_request(
             "PATCH",
@@ -195,20 +333,28 @@ def finalize_ephemeral_trace_batch(
     def mark_trace_batch_as_failed(
         self, trace_batch_id: str, error_message: str
     ) -> httpx.Response:
+        payload: TraceFailedPayload = {
+            "status": "failed",
+            "failure_reason": error_message,
+        }
         return self._make_request(
             "PATCH",
             f"{self.TRACING_RESOURCE}/batches/{trace_batch_id}",
-            json={"status": "failed", "failure_reason": error_message},
+            json=payload,
             timeout=30,
         )
 
     def mark_ephemeral_trace_batch_as_failed(
         self, trace_batch_id: str, error_message: str
     ) -> httpx.Response:
+        payload: TraceFailedPayload = {
+            "status": "failed",
+            "failure_reason": error_message,
+        }
         return self._make_request(
             "PATCH",
             f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}",
-            json={"status": "failed", "failure_reason": error_message},
+            json=payload,
             timeout=30,
         )