cloudcruise 0.0.1__py3-none-any.whl

cloudcruise/__init__.py

@@ -0,0 +1,114 @@
+from .cloudcruise import CloudCruise, CloudCruiseParams
+
+from .vault.types import (
+    VaultEntry,
+    GetVaultEntriesFilters,
+    ProxyConfig,
+    VaultPostPutHeadersInBody,
+)
+
+from .workflows.types import (
+    Workflow,
+    WorkflowInputSchema,
+    WorkflowMetadata,
+    InputValidationError,
+)
+
+from .runs.types import (
+    EventType,
+    DryRun,
+    Metadata,
+    RunSpecificWebhook,
+    PayloadWebhook,
+    StartRunRequest,
+    StartRunResponse,
+    UserInteractionData,
+    VideoUrl,
+    FileUrl,
+    ScreenshotUrl,
+    RunError,
+    RunResult,
+    WebhookEvent,
+    WebhookReplayResponse,
+    RunHandle,
+    RunStreamOptions,
+    SseEventName,
+    SseMessage,
+    RunEventEnvelope,
+    # Event payload types
+    ExecutionQueuedPayload,
+    ExecutionStartPayload,
+    ExecutionStepPayload,
+    InteractionWaitingPayload,
+    InteractionFinishedPayload,
+    AgentErrorAnalysisPayload,
+    ExecutionRequeuedPayload,
+    EndRunPayload,
+    EndRunError,
+    ExecutionStoppedEarlyPayload,
+    FileUploadedPayload,
+    ScreenshotUploadedPayload,
+    EventWebhookMessage,
+    RunEventMessage,
+)
+
+from .webhook.types import WebhookPayload, WebhookVerificationOptions, VerificationError, WebhookMessage
+from ._default import get_client as client
+
+__all__ = [
+    "CloudCruise",
+    "CloudCruiseParams",
+    # Default client helper
+    "client",
+    # Vault Types
+    "VaultEntry",
+    "GetVaultEntriesFilters",
+    "ProxyConfig",
+    "VaultPostPutHeadersInBody",
+    # Workflow Types
+    "Workflow",
+    "WorkflowInputSchema",
+    "WorkflowMetadata",
+    "InputValidationError",
+    # Run Types
+    "EventType",
+    "DryRun",
+    "Metadata",
+    "RunSpecificWebhook",
+    "PayloadWebhook",
+    "StartRunRequest",
+    "StartRunResponse",
+    "UserInteractionData",
+    "VideoUrl",
+    "FileUrl",
+    "ScreenshotUrl",
+    "RunError",
+    "RunResult",
+    "WebhookEvent",
+    "WebhookReplayResponse",
+    "RunHandle",
+    "RunStreamOptions",
+    "SseEventName",
+    "SseMessage",
+    "RunEventEnvelope",
+    # Event Payload Types
+    "ExecutionQueuedPayload",
+    "ExecutionStartPayload",
+    "ExecutionStepPayload",
+    "InteractionWaitingPayload",
+    "InteractionFinishedPayload",
+    "AgentErrorAnalysisPayload",
+    "ExecutionRequeuedPayload",
+    "EndRunPayload",
+    "EndRunError",
+    "ExecutionStoppedEarlyPayload",
+    "FileUploadedPayload",
+    "ScreenshotUploadedPayload",
+    "EventWebhookMessage",
+    "RunEventMessage",
+    # Webhook Types
+    "WebhookPayload",
+    "WebhookVerificationOptions",
+    "VerificationError",
+    "WebhookMessage",
+]

cloudcruise/_default.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .cloudcruise import CloudCruise, CloudCruiseParams
+
+_default_client: Optional[CloudCruise] = None
+
+
+def get_client(
+    params: Optional[CloudCruiseParams] = None,
+    *,
+    api_key: Optional[str] = None,
+    encryption_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> CloudCruise:
+    """Return the shared default CloudCruise client.
+
+    You can configure it by passing a CloudCruiseParams instance or via
+    keyword args (api_key, encryption_key, base_url). Passing any params or
+    keyword args replaces the cached client.
+    """
+    global _default_client
+
+    effective_params = params
+    if effective_params is None and (api_key is not None or encryption_key is not None or base_url is not None):
+        effective_params = CloudCruiseParams(api_key=api_key, encryption_key=encryption_key, base_url=base_url)
+
+    if effective_params is not None or _default_client is None:
+        _default_client = CloudCruise(effective_params)
+    return _default_client

cloudcruise/cloudcruise.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+import json
+import requests
+
+from .utils.env import get_env
+from .vault.client import VaultClient
+from .workflows.client import WorkflowsClient
+from .runs.client import RunsClient
+from .webhook.client import WebhookClient
+from .utils.connection_manager import ConnectionManager
+
+@dataclass
+class CloudCruiseParams:
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    encryption_key: Optional[str] = None
+
+
+class CloudCruise:
+    """
+    CloudCruise Python SDK
+    Official client library for the CloudCruise Platform
+    """
+
+    # Expose typed attributes for IDE autocomplete
+    vault: VaultClient
+    workflows: WorkflowsClient
+    runs: RunsClient
+    webhook: WebhookClient
+
+    def __init__(self, params: Optional[CloudCruiseParams] = None) -> None:
+        params = params or CloudCruiseParams()
+        api_key = params.api_key or get_env("CLOUDCRUISE_API_KEY")
+        base_url = params.base_url or get_env("CLOUDCRUISE_BASE_URL") or "https://api.cloudcruise.com"
+        encryption_key = params.encryption_key or get_env("CLOUDCRUISE_ENCRYPTION_KEY")
+
+        if not api_key:
+            raise ValueError("Missing apiKey. Provide via params.api_key or CLOUDCRUISE_API_KEY env var.")
+        if not encryption_key:
+            raise ValueError(
+                "Missing encryptionKey. Provide via params.encryption_key or CLOUDCRUISE_ENCRYPTION_KEY env var."
+            )
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._encryption_key = encryption_key
+
+        # Initialize namespace clients
+        self._connection_manager = ConnectionManager(self._base_url, self._api_key)
+        self.vault = VaultClient(self._make_request, self._encryption_key)
+        self.workflows = WorkflowsClient(self._make_request)
+        self.runs = RunsClient(self._connection_manager, self._make_request, self.workflows)
+        self.webhook = WebhookClient()
+
+    def _make_request(self, method: str, path: str, body: Optional[Any] = None) -> Any:
+        """
+        Makes an HTTP request to the CloudCruise API
+        Automatically adds the cc-key header for authentication
+        """
+        url = f"{self._base_url}{path}"
+        headers = {
+            "cc-key": self._api_key,
+        }
+        try:
+            # Only send Content-Type when we have a JSON body
+            if body is not None:
+                headers["Content-Type"] = "application/json"
+
+            resp = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                data=(json.dumps(body) if body is not None else None),
+                timeout=60,
+            )
+            if not resp.ok:
+                error_text = resp.text
+                error_message = f"HTTP {resp.status_code}: {resp.reason}"
+                try:
+                    error_json = resp.json()
+                    error_message = error_json.get("message") or error_json.get("error") or error_message
+                except Exception:
+                    pass
+                raise RuntimeError(error_message)
+
+            ctype = resp.headers.get("content-type", "")
+            if "application/json" in ctype:
+                return resp.json()
+
+            else:
+                return resp.text
+        except Exception as e:
+            raise e

cloudcruise/events/__init__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from .types import (
+    ExecutionQueuedPayload,
+    ExecutionStartPayload,
+    ExecutionStepPayload,
+    InteractionWaitingPayload,
+    InteractionFinishedPayload,
+    InteractionFinishedPayloadVariant1,
+    InteractionFinishedPayloadVariant2,
+    AgentErrorAnalysisPayload,
+    ExecutionRequeuedPayload,
+    EndRunPayload,
+    EndRunError,
+    ExecutionStoppedEarlyPayload,
+    FileUploadedPayload,
+    ScreenshotUploadedPayload,
+    WebhookMessage,
+    RunEventMessage,
+    RunEventMessageData,
+)
+
+__all__ = [
+    # Event payload types
+    "ExecutionQueuedPayload",
+    "ExecutionStartPayload",
+    "ExecutionStepPayload",
+    "InteractionWaitingPayload",
+    "InteractionFinishedPayload",
+    "InteractionFinishedPayloadVariant1",
+    "InteractionFinishedPayloadVariant2",
+    "AgentErrorAnalysisPayload",
+    "ExecutionRequeuedPayload",
+    "EndRunPayload",
+    "EndRunError",
+    "ExecutionStoppedEarlyPayload",
+    "FileUploadedPayload",
+    "ScreenshotUploadedPayload",
+    # Generic message types
+    "WebhookMessage",
+    "RunEventMessage",
+    "RunEventMessageData",
+]

cloudcruise/events/types.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Generic, List, Literal, TypeVar, TypedDict, Union
+
+# Re-use EventType from runs.types to avoid circular imports
+# We'll import it later after updating runs/types.py
+
+# Event Payload TypedDicts
+class ExecutionQueuedPayload(TypedDict):
+    session_id: str
+    workflow_id: str
+
+
+class ExecutionStartPayload(TypedDict, total=False):
+    session_id: str
+    workflow_id: str
+    live_view_url: str  # optional
+
+
+class ExecutionStepPayload(TypedDict):
+    session_id: str
+    workflow_id: str
+    current_step: str
+    next_step: str
+
+
+class InteractionWaitingPayload(TypedDict):
+    session_id: str
+    workflow_id: str
+    current_step: str
+    missing_properties: List[str]
+    expected_json_schema_datamodel: Dict[str, Any]
+    message: str
+
+
+# InteractionFinishedPayload has two possible shapes
+class InteractionFinishedPayloadVariant1(TypedDict):
+    session_id: str
+    workflow_id: str
+    current_step: str
+    missing_properties: List[str]  # empty list in this variant
+    expected_json_schema_datamodel: Dict[str, Any]
+    message: str
+
+
+class InteractionFinishedPayloadVariant2(TypedDict, total=False):
+    session_id: str
+    workflow_id: str
+    provided_input: Any
+    message: str  # optional
+    expected_json_schema_datamodel: Dict[str, Any]
+
+
+InteractionFinishedPayload = Union[
+    InteractionFinishedPayloadVariant1,
+    InteractionFinishedPayloadVariant2
+]
+
+
+class AgentErrorAnalysisPayload(TypedDict, total=False):
+    analysis_step_name: str
+    ai_analysis: str  # optional
+    root_cause_analysis: str  # optional
+    error_category: str  # optional
+
+
+class ExecutionRequeuedPayload(TypedDict, total=False):
+    session_id: str
+    workflow_id: str
+    retry_attempt: int
+    max_retries: int  # optional
+    next_execution_time: str
+    delay_ms: int
+
+
+class EndRunError(TypedDict, total=False):
+    message: str
+    error_id: str
+    full_url: str  # optional
+    created_at: str
+    error_code: str  # optional
+    action_type: str  # optional
+    action_display_name: str  # optional
+    llm_error_category: str  # optional
+
+
+class EndRunPayload(TypedDict, total=False):
+    session_id: str
+    workflow_id: str
+    data: Any
+    input_variables: Dict[str, Any]
+    errors: List[EndRunError]
+    status: Literal["execution.success", "execution.failed", "execution.stopped"]
+    encrypted_variables: Union[List[str], None]
+    file_urls: Union[List[Any], None]
+
+
+class ExecutionStoppedEarlyPayload(TypedDict):
+    message: str
+    error_code: str
+    session_id: str
+
+
+class FileUploadedPayload(TypedDict):
+    signed_file_url: str
+    file_name: str
+    timestamp: str
+    signed_file_url_expires: str
+    metadata: Dict[str, Any]
+    session_id: str
+
+
+class ScreenshotUploadedPayload(TypedDict):
+    screenshot_id: str
+    signed_screenshot_url: str
+    node_display_name: str
+    node_id: str
+    timestamp: str
+    signed_screenshot_url_expires: str
+    error_screenshot: bool
+    retry_index: int
+    full_length_screenshot: bool
+    session_id: str
+
+
+# Type variable for generic webhook messages
+E = TypeVar('E', bound=str)
+
+
+# Generic Webhook Message type
+class WebhookMessage(TypedDict, Generic[E], total=False):
+    event: E
+    timestamp: int
+    expires_at: int
+    payload: Any  # Will be typed more specifically with EventPayloadMap
+    metadata: Dict[str, Any]  # optional
+
+
+# Generic SSE Run Event Message type
+class RunEventMessageData(TypedDict, Generic[E]):
+    event: E
+    payload: Any
+    timestamp: int
+    expires_at: int
+
+
+class RunEventMessage(TypedDict, Generic[E]):
+    event: Literal["run.event"]
+    data: RunEventMessageData[E]
+    timestamp: str
+    expires_at: str

cloudcruise/runs/__init__.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .types import *  # re-export types for convenience
+
+def _client():
+    # Lazy import to avoid circular imports during package initialization
+    from .._default import get_client as _get_client
+    return _get_client()
+
+__all__ = [
+    "EventType",
+    "DryRun",
+    "Metadata",
+    "RunSpecificWebhook",
+    "PayloadWebhook",
+    "StartRunRequest",
+    "StartRunResponse",
+    "UserInteractionData",
+    "VideoUrl",
+    "FileUrl",
+    "ScreenshotUrl",
+    "RunError",
+    "RunResult",
+    "WebhookEvent",
+    "WebhookReplayResponse",
+    "RunHandle",
+    "RunStreamOptions",
+    "SseEventName",
+    "SseMessage",
+    "RunEventEnvelope",
+    # Convenience APIs
+    "start",
+    "subscribe_to_session",
+    "submit_user_interaction",
+    "get_results",
+    "interrupt",
+    "replay_webhooks",
+]
+
+
+def start(request: StartRunRequest, options: Optional[RunStreamOptions] = None) -> RunHandle:
+    return _client().runs.start(request, options)
+
+
+def subscribe_to_session(session_id: str, options: Optional[RunStreamOptions] = None) -> RunHandle:
+    return _client().runs.subscribe_to_session(session_id, options)
+
+
+def submit_user_interaction(session_id: str, data: UserInteractionData) -> None:
+    return _client().runs.submit_user_interaction(session_id, data)
+
+
+def get_results(session_id: str) -> RunResult:
+    return _client().runs.get_results(session_id)
+
+
+def interrupt(session_id: str) -> None:
+    return _client().runs.interrupt(session_id)
+
+
+def replay_webhooks(session_id: str) -> WebhookReplayResponse:
+    return _client().runs.replay_webhooks(session_id)