simplex 2.0.4__tar.gz → 3.0.1__tar.gz

{simplex-2.0.4/simplex.egg-info → simplex-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplex
-Version: 2.0.4
+Version: 3.0.1
 Summary: Official Python SDK for the Simplex API
 Author-email: Simplex <support@simplex.sh>
 License: MIT

{simplex-2.0.4 → simplex-3.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplex"
-version = "2.0.4"
+version = "3.0.1"
 description = "Official Python SDK for the Simplex API"
 readme = "README.md"
 requires-python = ">=3.9"

{simplex-2.0.4 → simplex-3.0.1}/simplex/__init__.py

@@ -31,11 +31,18 @@ from simplex.errors import (
 )
 from simplex.types import (
     FileMetadata,
+    PauseSessionResponse,
+    ResumeSessionResponse,
     RunWorkflowResponse,
+    SearchWorkflowItem,
+    SearchWorkflowsResponse,
     SessionStatusResponse,
+    UpdateWorkflowMetadataResponse,
+    WebhookPayload,
 )
+from simplex.webhook import WebhookVerificationError, verify_simplex_webhook
 
-__version__ = "2.0.4"
+__version__ = "3.0.1"
 __all__ = [
     "SimplexClient",
     "SimplexError",
@@ -47,4 +54,12 @@ __all__ = [
     "FileMetadata",
     "SessionStatusResponse",
     "RunWorkflowResponse",
+    "PauseSessionResponse",
+    "ResumeSessionResponse",
+    "SearchWorkflowsResponse",
+    "SearchWorkflowItem",
+    "UpdateWorkflowMetadataResponse",
+    "WebhookPayload",
+    "verify_simplex_webhook",
+    "WebhookVerificationError",
 ]

{simplex-2.0.4 → simplex-3.0.1}/simplex/_http_client.py

@@ -21,7 +21,7 @@ from simplex.errors import (
     ValidationError,
 )
 
-__version__ = "2.0.4"
+__version__ = "3.0.1"
 
 
 class HttpClient:

{simplex-2.0.4 → simplex-3.0.1}/simplex/client.py

@@ -12,7 +12,14 @@ from typing import Any
 
 from simplex._http_client import HttpClient
 from simplex.errors import WorkflowError
-from simplex.types import RunWorkflowResponse, SessionStatusResponse
+from simplex.types import (
+    PauseSessionResponse,
+    ResumeSessionResponse,
+    RunWorkflowResponse,
+    SearchWorkflowsResponse,
+    SessionStatusResponse,
+    UpdateWorkflowMetadataResponse,
+)
 
 
 class SimplexClient:
@@ -291,3 +298,165 @@ class SimplexClient:
                 f"Failed to retrieve session logs: {e}",
                 session_id=session_id,
             )
+
+    def pause(self, session_id: str) -> PauseSessionResponse:
+        """
+        Pause a running session.
+
+        Args:
+            session_id: The session ID to pause
+
+        Returns:
+            PauseSessionResponse with pause details
+
+        Raises:
+            WorkflowError: If pausing the session fails
+
+        Example:
+            >>> result = client.pause("session-123")
+            >>> print(f"Paused with key: {result['pause_key']}")
+        """
+        try:
+            response: PauseSessionResponse = self._http_client.post(
+                "/pause",
+                data={"session_id": session_id},
+            )
+            if not response.get("succeeded"):
+                raise WorkflowError(
+                    response.get("error", "Failed to pause session"),
+                    session_id=session_id,
+                )
+            return response
+        except Exception as e:
+            if isinstance(e, WorkflowError):
+                raise
+            raise WorkflowError(
+                f"Failed to pause session: {e}",
+                session_id=session_id,
+            )
+
+    def resume(self, session_id: str) -> ResumeSessionResponse:
+        """
+        Resume a paused session.
+
+        Args:
+            session_id: The session ID to resume
+
+        Returns:
+            ResumeSessionResponse with resume details
+
+        Raises:
+            WorkflowError: If resuming the session fails
+
+        Example:
+            >>> result = client.resume("session-123")
+            >>> print(f"Resumed, pause type: {result['pause_type']}")
+        """
+        try:
+            response: ResumeSessionResponse = self._http_client.post(
+                "/resume_session",
+                data={"session_id": session_id},
+            )
+            if not response.get("succeeded"):
+                raise WorkflowError(
+                    response.get("error", "Failed to resume session"),
+                    session_id=session_id,
+                )
+            return response
+        except Exception as e:
+            if isinstance(e, WorkflowError):
+                raise
+            raise WorkflowError(
+                f"Failed to resume session: {e}",
+                session_id=session_id,
+            )
+
+    def search_workflows(
+        self,
+        workflow_name: str | None = None,
+        metadata: str | None = None,
+    ) -> SearchWorkflowsResponse:
+        """
+        Search workflows by name and/or metadata.
+
+        At least one of workflow_name or metadata must be provided.
+
+        Args:
+            workflow_name: Name of the workflow to search for
+            metadata: Metadata string to search for
+
+        Returns:
+            SearchWorkflowsResponse with matching workflows
+
+        Raises:
+            ValueError: If neither workflow_name nor metadata is provided
+            WorkflowError: If the search fails
+
+        Example:
+            >>> results = client.search_workflows(workflow_name="my-workflow")
+            >>> for wf in results["workflows"]:
+            ...     print(f"{wf['workflow_name']} ({wf['workflow_id']})")
+        """
+        if workflow_name is None and metadata is None:
+            raise ValueError("At least one of workflow_name or metadata must be provided")
+
+        params: dict[str, str] = {}
+        if workflow_name is not None:
+            params["workflow_name"] = workflow_name
+        if metadata is not None:
+            params["metadata"] = metadata
+
+        try:
+            response: SearchWorkflowsResponse = self._http_client.get(
+                "/search_workflows",
+                params=params,
+            )
+            return response
+        except Exception as e:
+            if isinstance(e, WorkflowError):
+                raise
+            raise WorkflowError(f"Failed to search workflows: {e}")
+
+    def update_workflow_metadata(
+        self,
+        workflow_id: str,
+        metadata: str,
+    ) -> UpdateWorkflowMetadataResponse:
+        """
+        Update the metadata of a workflow.
+
+        Args:
+            workflow_id: The ID of the workflow to update
+            metadata: The new metadata string
+
+        Returns:
+            UpdateWorkflowMetadataResponse with update confirmation
+
+        Raises:
+            WorkflowError: If updating the metadata fails
+
+        Example:
+            >>> result = client.update_workflow_metadata(
+            ...     "workflow-123",
+            ...     "new-metadata-value"
+            ... )
+            >>> print(f"Updated: {result['message']}")
+        """
+        try:
+            response: UpdateWorkflowMetadataResponse = self._http_client.post(
+                "/update_workflow_metadata",
+                data={"workflow_id": workflow_id, "metadata": metadata},
+            )
+            if not response.get("succeeded"):
+                raise WorkflowError(
+                    "Failed to update workflow metadata",
+                    workflow_id=workflow_id,
+                )
+            return response
+        except Exception as e:
+            if isinstance(e, WorkflowError):
+                raise
+            raise WorkflowError(
+                f"Failed to update workflow metadata: {e}",
+                workflow_id=workflow_id,
+            )

simplex-3.0.1/simplex/types.py

@@ -0,0 +1,188 @@
+"""
+Type definitions for the Simplex SDK.
+
+This module contains TypedDict classes used for type hinting throughout the SDK.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class FileMetadata(TypedDict):
+    """
+    Metadata for a file downloaded or created during a session.
+
+    Attributes:
+        filename: The filename
+        download_url: The URL the file was downloaded from
+        file_size: File size in bytes
+        download_timestamp: ISO timestamp when the file was downloaded/created
+    """
+
+    filename: str
+    download_url: str
+    file_size: int
+    download_timestamp: str
+
+
+class SessionStatusResponse(TypedDict, total=False):
+    """
+    Response from polling session status.
+
+    Attributes:
+        in_progress: Whether the session is still running
+        success: Whether the session completed successfully (None while in progress)
+        metadata: Custom metadata provided when the session was started
+        workflow_metadata: Metadata from the workflow definition
+        file_metadata: Metadata for files downloaded during the session
+        scraper_outputs: Scraper outputs collected during the session, keyed by output name
+        structured_output: Structured output fields from workflow execution (None while in progress)
+        paused: Whether the session is currently paused
+        paused_key: The pause key if the session is paused
+    """
+
+    in_progress: bool
+    success: bool | None
+    metadata: dict[str, Any]
+    workflow_metadata: dict[str, Any]
+    file_metadata: list[FileMetadata]
+    scraper_outputs: dict[str, Any]
+    structured_output: dict[str, Any] | None
+    paused: bool
+    paused_key: str
+
+
+class RunWorkflowResponse(TypedDict):
+    """
+    Response from running a workflow.
+
+    Attributes:
+        succeeded: Whether the workflow started successfully
+        message: Human-readable status message
+        session_id: Unique identifier for this workflow session
+        vnc_url: URL for VNC access to the workflow session
+        logs_url: URL for viewing session logs
+    """
+
+    succeeded: bool
+    message: str
+    session_id: str
+    vnc_url: str
+    logs_url: str
+
+
+class PauseSessionResponse(TypedDict, total=False):
+    """
+    Response from pausing a session.
+
+    Attributes:
+        succeeded: Whether the pause operation succeeded
+        action: The action that was performed
+        pause_key: The key associated with the pause
+        error: Error message if the operation failed
+    """
+
+    succeeded: bool
+    action: str
+    pause_key: str
+    error: str
+
+
+class ResumeSessionResponse(TypedDict, total=False):
+    """
+    Response from resuming a paused session.
+
+    Attributes:
+        succeeded: Whether the resume operation succeeded
+        action: The action that was performed
+        pause_type: The type of pause ('external' or 'internal')
+        key: The key associated with the pause
+        error: Error message if the operation failed
+    """
+
+    succeeded: bool
+    action: str
+    pause_type: str
+    key: str
+    error: str
+
+
+class SearchWorkflowItem(TypedDict, total=False):
+    """
+    A single workflow item returned from a search.
+
+    Attributes:
+        workflow_id: The workflow's unique identifier
+        workflow_name: The workflow's name
+        variables: Variables defined in the workflow
+        metadata: Optional metadata string
+    """
+
+    workflow_id: str
+    workflow_name: str
+    variables: dict[str, Any]
+    metadata: str
+
+
+class SearchWorkflowsResponse(TypedDict):
+    """
+    Response from searching workflows.
+
+    Attributes:
+        succeeded: Whether the search succeeded
+        workflows: List of matching workflows
+        count: Total number of matching workflows
+    """
+
+    succeeded: bool
+    workflows: list[SearchWorkflowItem]
+    count: int
+
+
+class UpdateWorkflowMetadataResponse(TypedDict):
+    """
+    Response from updating workflow metadata.
+
+    Attributes:
+        succeeded: Whether the update succeeded
+        message: Human-readable status message
+        workflow_id: The workflow that was updated
+        metadata: The updated metadata string
+    """
+
+    succeeded: bool
+    message: str
+    workflow_id: str
+    metadata: str
+
+
+class WebhookPayload(TypedDict, total=False):
+    """
+    Payload received from a Simplex webhook.
+
+    Attributes:
+        success: Whether the session completed successfully
+        agent_response: The agent's response text
+        session_id: The session identifier
+        file_metadata: Metadata for files created during the session
+        scraper_outputs: Scraper outputs collected during the session
+        session_metadata: Custom metadata attached to the session
+        workflow_id: The workflow identifier
+        workflow_metadata: Metadata from the workflow definition
+        workflow_result: The workflow execution result
+        structured_output: Structured output from the workflow
+        screenshot_url: URL to a screenshot taken during the session
+    """
+
+    success: bool
+    agent_response: str
+    session_id: str
+    file_metadata: list[FileMetadata]
+    scraper_outputs: dict[str, Any]
+    session_metadata: dict[str, Any]
+    workflow_id: str
+    workflow_metadata: dict[str, Any]
+    workflow_result: dict[str, Any]
+    structured_output: dict[str, Any]
+    screenshot_url: str

simplex-3.0.1/simplex/webhook.py

@@ -0,0 +1,70 @@
+"""
+Webhook verification for the Simplex SDK.
+
+This module provides utilities to verify incoming Simplex webhook requests
+using HMAC-SHA256 signature verification.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+class WebhookVerificationError(Exception):
+    """Raised when webhook signature verification fails."""
+
+
+def verify_simplex_webhook(
+    body: str,
+    headers: dict[str, str],
+    webhook_secret: str,
+) -> None:
+    """
+    Verify a Simplex webhook request using HMAC-SHA256 signature verification.
+
+    This function ensures that webhook requests are authentic and haven't been
+    tampered with in transit.
+
+    Args:
+        body: Raw request body as a string (must be the original unparsed body)
+        headers: Request headers dict containing the X-Simplex-Signature header
+        webhook_secret: Your webhook secret from the Simplex dashboard
+
+    Raises:
+        WebhookVerificationError: If the signature is missing, invalid,
+            or verification fails
+
+    Example:
+        >>> # Flask example
+        >>> from flask import Flask, request
+        >>> from simplex import verify_simplex_webhook, WebhookPayload
+        >>>
+        >>> @app.route("/webhook", methods=["POST"])
+        >>> def webhook():
+        ...     body = request.get_data(as_text=True)
+        ...     verify_simplex_webhook(body, dict(request.headers), WEBHOOK_SECRET)
+        ...     payload: WebhookPayload = request.get_json()
+        ...     print(f"Session: {payload['session_id']}")
+        ...     return {"success": True}
+    """
+    # Normalize header lookup (case-insensitive)
+    signature = None
+    for key, value in headers.items():
+        if key.lower() == "x-simplex-signature":
+            signature = value
+            break
+
+    if not signature:
+        raise WebhookVerificationError("Missing X-Simplex-Signature header")
+
+    # Compute expected signature
+    expected_signature = hmac.new(
+        webhook_secret.encode("utf-8"),
+        body.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Constant-time comparison to prevent timing attacks
+    if not hmac.compare_digest(signature, expected_signature):
+        raise WebhookVerificationError("Invalid webhook signature")

{simplex-2.0.4 → simplex-3.0.1/simplex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplex
-Version: 2.0.4
+Version: 3.0.1
 Summary: Official Python SDK for the Simplex API
 Author-email: Simplex <support@simplex.sh>
 License: MIT

{simplex-2.0.4 → simplex-3.0.1}/simplex.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ simplex/_http_client.py
 simplex/client.py
 simplex/errors.py
 simplex/types.py
+simplex/webhook.py
 simplex.egg-info/PKG-INFO
 simplex.egg-info/SOURCES.txt
 simplex.egg-info/dependency_links.txt

simplex-2.0.4/simplex/types.py

@@ -1,70 +0,0 @@
-"""
-Type definitions for the Simplex SDK.
-
-This module contains TypedDict classes used for type hinting throughout the SDK.
-"""
-
-from __future__ import annotations
-
-from typing import Any, TypedDict
-
-
-class FileMetadata(TypedDict):
-    """
-    Metadata for a file downloaded or created during a session.
-
-    Attributes:
-        filename: The filename
-        download_url: The URL the file was downloaded from
-        file_size: File size in bytes
-        download_timestamp: ISO timestamp when the file was downloaded/created
-    """
-
-    filename: str
-    download_url: str
-    file_size: int
-    download_timestamp: str
-
-
-class SessionStatusResponse(TypedDict, total=False):
-    """
-    Response from polling session status.
-
-    Attributes:
-        in_progress: Whether the session is still running
-        success: Whether the session completed successfully (None while in progress)
-        metadata: Custom metadata provided when the session was started
-        workflow_metadata: Metadata from the workflow definition
-        file_metadata: Metadata for files downloaded during the session
-        scraper_outputs: Scraper outputs collected during the session, keyed by output name
-        paused: Whether the session is currently paused
-        paused_key: The pause key if the session is paused
-    """
-
-    in_progress: bool
-    success: bool | None
-    metadata: dict[str, Any]
-    workflow_metadata: dict[str, Any]
-    file_metadata: list[FileMetadata]
-    scraper_outputs: dict[str, Any]
-    paused: bool
-    paused_key: str
-
-
-class RunWorkflowResponse(TypedDict):
-    """
-    Response from running a workflow.
-
-    Attributes:
-        succeeded: Whether the workflow started successfully
-        message: Human-readable status message
-        session_id: Unique identifier for this workflow session
-        vnc_url: URL for VNC access to the workflow session
-        logs_url: URL for viewing session logs
-    """
-
-    succeeded: bool
-    message: str
-    session_id: str
-    vnc_url: str
-    logs_url: str