cyberdesk 2.1.16__tar.gz → 2.1.18__tar.gz

{cyberdesk-2.1.16/cyberdesk.egg-info → cyberdesk-2.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cyberdesk
-Version: 2.1.16
+Version: 2.1.18
 Summary: The official Python SDK for Cyberdesk
 Author-email: Cyberdesk Team <dev@cyberdesk.io>
 License-Expression: MIT
@@ -12,6 +12,23 @@ Provides-Extra: dev
 Requires-Dist: openapi-python-client; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Provides-Extra: testing
+Requires-Dist: svix>=1.0.0; extra == "testing"
+Requires-Dist: fastapi>=0.100.0; extra == "testing"
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == "testing"
+Requires-Dist: python-dotenv>=1.0.0; extra == "testing"
+Requires-Dist: pytest>=8.0.0; extra == "testing"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "testing"
+Provides-Extra: all
+Requires-Dist: openapi-python-client; extra == "all"
+Requires-Dist: build; extra == "all"
+Requires-Dist: twine; extra == "all"
+Requires-Dist: svix>=1.0.0; extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Requires-Dist: pytest>=8.0.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "all"
 Dynamic: license-file
 
 # Cyberdesk Python SDK
@@ -21,7 +38,14 @@ The official Python SDK for Cyberdesk API. This SDK provides a clean, type-safe
 ## Installation
 
 ```bash
+# Basic SDK installation
 pip install cyberdesk
+
+# With testing utilities
+pip install "cyberdesk[testing]"
+
+# All development dependencies (for SDK contributors)
+pip install "cyberdesk[all]"
 ```
 
 ## Quick Start
@@ -66,6 +90,38 @@ else:
         print("Run failed:", ", ".join(run.error or []))
 ```
 
+## Desktop Parameters
+
+Configure machine-specific values that automatically populate workflows running on specific desktops:
+
+```python
+from cyberdesk import MachineUpdate
+
+# Set desktop parameters for a machine
+client.machines.update_sync(
+    machine_id="machine-id",
+    data=MachineUpdate(
+        machine_parameters={
+            "username": "machine_specific_user",
+            "api_url": "https://api-region-east.example.com",
+            "config_path": "C:\\MachineA\\config.json"
+        },
+        machine_sensitive_parameters={
+            "password": "actual_secret_value",  # Stored securely in Basis Theory
+            "api_key": "actual_api_key_123"
+        }
+    )
+)
+```
+
+Use in workflows with standard syntax:
+```
+Log in to {api_url} using {username} and password {$password}.
+Then open the config at {config_path}.
+```
+
+Desktop parameters automatically override run-level inputs and persist across runs. See the [Desktop Parameters docs](https://docs.cyberdesk.io/concepts/desktop-parameters) for more details.
+
 ## Full Documentation
 
 For complete documentation including async/sync usage, error handling, and all available methods, visit:
@@ -281,6 +337,106 @@ from cyberdesk import (
 )
 ```
 
+## Webhooks
+
+### Handling Webhooks
+
+Cyberdesk sends webhooks when important events occur (e.g., workflow completion). To handle webhooks:
+
+```python
+import os
+from fastapi import FastAPI, Request, HTTPException
+from svix.webhooks import Webhook, WebhookVerificationError
+from openapi_client.cyberdesk_cloud_client.models.run_completed_event import RunCompletedEvent
+from openapi_client.cyberdesk_cloud_client.models.run_response import RunResponse
+from typing import cast
+
+app = FastAPI()
+
+@app.post("/webhooks/cyberdesk")
+async def cyberdesk_webhook(request: Request):
+    secret = os.environ["SVIX_WEBHOOK_SECRET"]
+    wh = Webhook(secret)
+    
+    payload = await request.body()
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    
+    try:
+        data = wh.verify(payload, headers)
+        # IMPORTANT: Use from_dict() for attrs classes, NOT model_validate()
+        evt = RunCompletedEvent.from_dict(data)
+        run: RunResponse = cast(RunResponse, evt.run)
+        
+        # Process the run based on status
+        if run.status == "success":
+            print(f"Run {run.id} completed successfully!")
+            print(f"Output: {run.output_data}")
+        
+        return {"ok": True}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+```
+
+**Important**: The SDK uses `attrs` classes (not Pydantic), so use `RunCompletedEvent.from_dict(data)` instead of `model_validate(data)`.
+
+### Testing Webhooks Locally
+
+See [tests/webhooks/WEBHOOK_TESTING.md](./tests/webhooks/WEBHOOK_TESTING.md) for a complete guide on testing webhooks locally without exposing your server to the internet.
+
+Quick start:
+```bash
+# Install SDK with testing dependencies
+pip install "cyberdesk[testing]"
+
+# Set up .env file
+cp .env.example .env
+# Edit .env with your SVIX_WEBHOOK_SECRET
+
+# Run the example webhook handler
+python -m uvicorn tests.webhooks.example_webhook_handler:app --reload
+
+# In another terminal, test it
+python -m tests.webhooks.test_webhook_local
+```
+
+### Example Files
+
+All webhook testing resources are in the `tests/webhooks/` directory:
+- `tests/webhooks/example_webhook_handler.py` - Complete, production-ready webhook handler
+- `tests/webhooks/test_webhook_local.py` - Utility to test webhooks locally
+- `tests/webhooks/test_webhook_integration.py` - pytest integration tests
+- `tests/webhooks/WEBHOOK_TESTING.md` - Comprehensive testing guide
+- `tests/webhooks/WEBHOOK_QUICKSTART.md` - Quick reference guide
+
+## Testing
+
+The SDK includes comprehensive testing utilities:
+
+### Quick Test
+
+```bash
+# Install with test dependencies
+pip install ".[testing]"
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run all tests
+pytest tests/ -v
+```
+
+### Test Categories
+
+- **Webhook Tests** (`tests/webhooks/`) - Test webhook handlers locally, no real API
+- **Integration Tests** (`tests/integration/`) - Test SDK with real API calls
+
+See [TESTING.md](./TESTING.md) for complete testing documentation.
+
 ## Limitations
 
 - **Screenshot API**: The `/v1/computer/{machine_id}/display/screenshot` endpoint is not included in the generated client due to limitations with binary (PNG) responses in the openapi-python-client generator. This can be added manually if needed - see the TODO comment in `client.py`.
@@ -289,7 +445,7 @@ from cyberdesk import (
 
 - Python 3.8+
 - httpx
-- pydantic
+- attrs (used by the auto-generated OpenAPI client)
 
 ## License
 

cyberdesk-2.1.16/PKG-INFO → cyberdesk-2.1.18/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: cyberdesk
-Version: 2.1.16
-Summary: The official Python SDK for Cyberdesk
-Author-email: Cyberdesk Team <dev@cyberdesk.io>
-License-Expression: MIT
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx
-Requires-Dist: attrs
-Provides-Extra: dev
-Requires-Dist: openapi-python-client; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Dynamic: license-file
-
 # Cyberdesk Python SDK
 
 The official Python SDK for Cyberdesk API. This SDK provides a clean, type-safe interface for interacting with all Cyberdesk resources including machines, workflows, runs, connections, and trajectories.
@@ -21,7 +5,14 @@ The official Python SDK for Cyberdesk API. This SDK provides a clean, type-safe
 ## Installation
 
 ```bash
+# Basic SDK installation
 pip install cyberdesk
+
+# With testing utilities
+pip install "cyberdesk[testing]"
+
+# All development dependencies (for SDK contributors)
+pip install "cyberdesk[all]"
 ```
 
 ## Quick Start
@@ -66,6 +57,38 @@ else:
         print("Run failed:", ", ".join(run.error or []))
 ```
 
+## Desktop Parameters
+
+Configure machine-specific values that automatically populate workflows running on specific desktops:
+
+```python
+from cyberdesk import MachineUpdate
+
+# Set desktop parameters for a machine
+client.machines.update_sync(
+    machine_id="machine-id",
+    data=MachineUpdate(
+        machine_parameters={
+            "username": "machine_specific_user",
+            "api_url": "https://api-region-east.example.com",
+            "config_path": "C:\\MachineA\\config.json"
+        },
+        machine_sensitive_parameters={
+            "password": "actual_secret_value",  # Stored securely in Basis Theory
+            "api_key": "actual_api_key_123"
+        }
+    )
+)
+```
+
+Use in workflows with standard syntax:
+```
+Log in to {api_url} using {username} and password {$password}.
+Then open the config at {config_path}.
+```
+
+Desktop parameters automatically override run-level inputs and persist across runs. See the [Desktop Parameters docs](https://docs.cyberdesk.io/concepts/desktop-parameters) for more details.
+
 ## Full Documentation
 
 For complete documentation including async/sync usage, error handling, and all available methods, visit:
@@ -281,6 +304,106 @@ from cyberdesk import (
 )
 ```
 
+## Webhooks
+
+### Handling Webhooks
+
+Cyberdesk sends webhooks when important events occur (e.g., workflow completion). To handle webhooks:
+
+```python
+import os
+from fastapi import FastAPI, Request, HTTPException
+from svix.webhooks import Webhook, WebhookVerificationError
+from openapi_client.cyberdesk_cloud_client.models.run_completed_event import RunCompletedEvent
+from openapi_client.cyberdesk_cloud_client.models.run_response import RunResponse
+from typing import cast
+
+app = FastAPI()
+
+@app.post("/webhooks/cyberdesk")
+async def cyberdesk_webhook(request: Request):
+    secret = os.environ["SVIX_WEBHOOK_SECRET"]
+    wh = Webhook(secret)
+    
+    payload = await request.body()
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    
+    try:
+        data = wh.verify(payload, headers)
+        # IMPORTANT: Use from_dict() for attrs classes, NOT model_validate()
+        evt = RunCompletedEvent.from_dict(data)
+        run: RunResponse = cast(RunResponse, evt.run)
+        
+        # Process the run based on status
+        if run.status == "success":
+            print(f"Run {run.id} completed successfully!")
+            print(f"Output: {run.output_data}")
+        
+        return {"ok": True}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+```
+
+**Important**: The SDK uses `attrs` classes (not Pydantic), so use `RunCompletedEvent.from_dict(data)` instead of `model_validate(data)`.
+
+### Testing Webhooks Locally
+
+See [tests/webhooks/WEBHOOK_TESTING.md](./tests/webhooks/WEBHOOK_TESTING.md) for a complete guide on testing webhooks locally without exposing your server to the internet.
+
+Quick start:
+```bash
+# Install SDK with testing dependencies
+pip install "cyberdesk[testing]"
+
+# Set up .env file
+cp .env.example .env
+# Edit .env with your SVIX_WEBHOOK_SECRET
+
+# Run the example webhook handler
+python -m uvicorn tests.webhooks.example_webhook_handler:app --reload
+
+# In another terminal, test it
+python -m tests.webhooks.test_webhook_local
+```
+
+### Example Files
+
+All webhook testing resources are in the `tests/webhooks/` directory:
+- `tests/webhooks/example_webhook_handler.py` - Complete, production-ready webhook handler
+- `tests/webhooks/test_webhook_local.py` - Utility to test webhooks locally
+- `tests/webhooks/test_webhook_integration.py` - pytest integration tests
+- `tests/webhooks/WEBHOOK_TESTING.md` - Comprehensive testing guide
+- `tests/webhooks/WEBHOOK_QUICKSTART.md` - Quick reference guide
+
+## Testing
+
+The SDK includes comprehensive testing utilities:
+
+### Quick Test
+
+```bash
+# Install with test dependencies
+pip install ".[testing]"
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run all tests
+pytest tests/ -v
+```
+
+### Test Categories
+
+- **Webhook Tests** (`tests/webhooks/`) - Test webhook handlers locally, no real API
+- **Integration Tests** (`tests/integration/`) - Test SDK with real API calls
+
+See [TESTING.md](./TESTING.md) for complete testing documentation.
+
 ## Limitations
 
 - **Screenshot API**: The `/v1/computer/{machine_id}/display/screenshot` endpoint is not included in the generated client due to limitations with binary (PNG) responses in the openapi-python-client generator. This can be added manually if needed - see the TODO comment in `client.py`.
@@ -289,8 +412,8 @@ from cyberdesk import (
 
 - Python 3.8+
 - httpx
-- pydantic
+- attrs (used by the auto-generated OpenAPI client)
 
 ## License
 
-MIT License - see LICENSE file for details. 
+MIT License - see LICENSE file for details. 

{cyberdesk-2.1.16 → cyberdesk-2.1.18}/cyberdesk/__init__.py

@@ -27,7 +27,7 @@ from .client import (
     AttachmentType,
 )
 
-__version__ = "2.1.16"
+__version__ = "2.1.18"
 
 __all__ = [
     "CyberdeskClient",