cloudcruise 0.0.1__tar.gz

cloudcruise-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CloudCruise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cloudcruise-0.0.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: cloudcruise
+Version: 0.0.1
+Summary: The official CloudCruise Python SDK
+Author-email: CloudCruise <founders@cloudcruise.com>
+License: MIT License
+Project-URL: Homepage, https://cloudcruise.com
+Project-URL: Documentation, https://docs.cloudcruise.com
+Project-URL: Repository, https://github.com/CloudCruise/cloudcruise-python
+Project-URL: Issues, https://github.com/CloudCruise/cloudcruise-python/issues
+Project-URL: Discord, https://discord.com/invite/MHjbUqedZF
+Keywords: cloudcruise,sdk,automation,workflows,sse,webhook
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# cloudcruise-python
+
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](LICENSE)
+![PyPI - Version](https://img.shields.io/pypi/v/cloudcruise?style=flat-square)
+![PyPI - Downloads](https://img.shields.io/pypi/dw/cloudcruise?style=flat-square)
+[![GitHub Repo stars](https://img.shields.io/github/stars/CloudCruise/cloudcruise-python?style=flat-square&logo=GitHub&label=cloudcruise-python)](https://github.com/CloudCruise/cloudcruise-python)
+[![Discord](https://img.shields.io/discord/1227480834945318933?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.com/invite/MHjbUqedZF)
+[![YC W24](https://img.shields.io/badge/Y%20Combinator-W24-orange?style=flat-square)](https://www.ycombinator.com/companies/cloudcruise)
+
+The official CloudCruise Python SDK for automated browser workflows, encrypted
+credential management, realtime run monitoring, and webhook verification.
+
+---
+
+## Installation
+
+```bash
+pip install cloudcruise
+```
+
+Python 3.10 or newer is required. The package ships with type hints (`py.typed`).
+
+---
+
+## Quick Start
+
+```python
+from cloudcruise import CloudCruise, StartRunRequest
+
+client = CloudCruise(
+    api_key="<CLOUDCRUISE_API_KEY>",
+    encryption_key="<CLOUDCRUISE_ENCRYPTION_KEY>",
+)
+# Alternatively, set CLOUDCRUISE_API_KEY and CLOUDCRUISE_ENCRYPTION_KEY
+# environment variables and instantiate with `client = CloudCruise()`.
+
+run = client.runs.start(
+    StartRunRequest(
+        workflow_id="105b7ae1-ce62-4a5c-b782-b4b0aec5175a",
+        run_input_variables={"email": "test@example.com"},
+    )
+)
+
+# Listen to specific event types (recommended - clean and type-safe)
+run.on("execution.start", lambda e: print(f"Workflow started: {e['payload']['workflow_id']}"))
+run.on("execution.step", lambda e: print(f"Step: {e['payload']['current_step']}"))
+run.on("execution.success", lambda e: print(f"Success! Output: {e['payload'].get('data')}"))
+run.on("end", lambda info: print(f"Run completed: {info['type']}"))
+
+# Or use generic listener for all events (flattened structure)
+# run.on("run.event", lambda event: print(f"{event['type']}: {event['payload']}"))
+
+# Block until the run finishes and fetch final results
+result = run.wait()
+print(result.status, result.data)
+```
+
+Environment variables `CLOUDCRUISE_API_KEY`, `CLOUDCRUISE_ENCRYPTION_KEY` are also supported via lazy `cloudcruise.client()`.
+
+---
+
+## Clients
+
+| Client                                   | Description                                            | Module Docs                                        |
+| ---------------------------------------- | ------------------------------------------------------ | -------------------------------------------------- |
+| [**Vault**](./cloudcruise/vault)         | AES-256-GCM credential storage and retrieval utilities | [`cloudcruise.vault`](./cloudcruise/vault)         |
+| [**Workflows**](./cloudcruise/workflows) | Workflow definitions, metadata, and input validation   | [`cloudcruise.workflows`](./cloudcruise/workflows) |
+| [**Runs**](./cloudcruise/runs)           | Workflow execution with SSE-based realtime streaming   | [`cloudcruise.runs`](./cloudcruise/runs)           |
+| [**Webhook**](./cloudcruise/webhook)     | Webhook payload verification and helpers               | [`cloudcruise.webhook`](./cloudcruise/webhook)     |
+
+All clients are accessible via `CloudCruise` or the convenience `cloudcruise.client()` singleton.
+
+---
+
+## Development
+
+This project uses standard Python tooling with `setuptools`. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for comprehensive instructions.
+
+Quick start:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"  # installs package + dev dependencies
+
+# Run the unit test suite
+python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+For live staging tests, export `CLOUDCRUISE_API_KEY` and
+`CLOUDCRUISE_ENCRYPTION_KEY`, then run `python -m unittest tests/test_live_staging.py -v`.
+
+---
+
+## Documentation & Resources
+
+- [API Documentation](https://docs.cloudcruise.com) – Full platform reference
+- [CloudCruise Platform](https://cloudcruise.com) – Product overview
+- [Agents & Assistant Context](./AGENTS.md) – How this repository’s automation assistant operates
+
+---
+
+## License
+
+[MIT](LICENSE)

cloudcruise-0.0.1/README.md

@@ -0,0 +1,106 @@
+# cloudcruise-python
+
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](LICENSE)
+![PyPI - Version](https://img.shields.io/pypi/v/cloudcruise?style=flat-square)
+![PyPI - Downloads](https://img.shields.io/pypi/dw/cloudcruise?style=flat-square)
+[![GitHub Repo stars](https://img.shields.io/github/stars/CloudCruise/cloudcruise-python?style=flat-square&logo=GitHub&label=cloudcruise-python)](https://github.com/CloudCruise/cloudcruise-python)
+[![Discord](https://img.shields.io/discord/1227480834945318933?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.com/invite/MHjbUqedZF)
+[![YC W24](https://img.shields.io/badge/Y%20Combinator-W24-orange?style=flat-square)](https://www.ycombinator.com/companies/cloudcruise)
+
+The official CloudCruise Python SDK for automated browser workflows, encrypted
+credential management, realtime run monitoring, and webhook verification.
+
+---
+
+## Installation
+
+```bash
+pip install cloudcruise
+```
+
+Python 3.10 or newer is required. The package ships with type hints (`py.typed`).
+
+---
+
+## Quick Start
+
+```python
+from cloudcruise import CloudCruise, StartRunRequest
+
+client = CloudCruise(
+    api_key="<CLOUDCRUISE_API_KEY>",
+    encryption_key="<CLOUDCRUISE_ENCRYPTION_KEY>",
+)
+# Alternatively, set CLOUDCRUISE_API_KEY and CLOUDCRUISE_ENCRYPTION_KEY
+# environment variables and instantiate with `client = CloudCruise()`.
+
+run = client.runs.start(
+    StartRunRequest(
+        workflow_id="105b7ae1-ce62-4a5c-b782-b4b0aec5175a",
+        run_input_variables={"email": "test@example.com"},
+    )
+)
+
+# Listen to specific event types (recommended - clean and type-safe)
+run.on("execution.start", lambda e: print(f"Workflow started: {e['payload']['workflow_id']}"))
+run.on("execution.step", lambda e: print(f"Step: {e['payload']['current_step']}"))
+run.on("execution.success", lambda e: print(f"Success! Output: {e['payload'].get('data')}"))
+run.on("end", lambda info: print(f"Run completed: {info['type']}"))
+
+# Or use generic listener for all events (flattened structure)
+# run.on("run.event", lambda event: print(f"{event['type']}: {event['payload']}"))
+
+# Block until the run finishes and fetch final results
+result = run.wait()
+print(result.status, result.data)
+```
+
+Environment variables `CLOUDCRUISE_API_KEY`, `CLOUDCRUISE_ENCRYPTION_KEY` are also supported via lazy `cloudcruise.client()`.
+
+---
+
+## Clients
+
+| Client                                   | Description                                            | Module Docs                                        |
+| ---------------------------------------- | ------------------------------------------------------ | -------------------------------------------------- |
+| [**Vault**](./cloudcruise/vault)         | AES-256-GCM credential storage and retrieval utilities | [`cloudcruise.vault`](./cloudcruise/vault)         |
+| [**Workflows**](./cloudcruise/workflows) | Workflow definitions, metadata, and input validation   | [`cloudcruise.workflows`](./cloudcruise/workflows) |
+| [**Runs**](./cloudcruise/runs)           | Workflow execution with SSE-based realtime streaming   | [`cloudcruise.runs`](./cloudcruise/runs)           |
+| [**Webhook**](./cloudcruise/webhook)     | Webhook payload verification and helpers               | [`cloudcruise.webhook`](./cloudcruise/webhook)     |
+
+All clients are accessible via `CloudCruise` or the convenience `cloudcruise.client()` singleton.
+
+---
+
+## Development
+
+This project uses standard Python tooling with `setuptools`. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for comprehensive instructions.
+
+Quick start:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"  # installs package + dev dependencies
+
+# Run the unit test suite
+python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+For live staging tests, export `CLOUDCRUISE_API_KEY` and
+`CLOUDCRUISE_ENCRYPTION_KEY`, then run `python -m unittest tests/test_live_staging.py -v`.
+
+---
+
+## Documentation & Resources
+
+- [API Documentation](https://docs.cloudcruise.com) – Full platform reference
+- [CloudCruise Platform](https://cloudcruise.com) – Product overview
+- [Agents & Assistant Context](./AGENTS.md) – How this repository’s automation assistant operates
+
+---
+
+## License
+
+[MIT](LICENSE)

cloudcruise-0.0.1/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-0.0.1/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-0.0.1/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-0.0.1/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",
+]