centcom 1.0.0__tar.gz

centcom-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/

centcom-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contro1
+
+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.

centcom-1.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.3
+Name: centcom
+Version: 1.0.0
+Summary: Official CENTCOM Python SDK for requests and webhook verification
+Project-URL: Homepage, https://contro1.com
+Project-URL: Documentation, https://contro1.com/docs
+Project-URL: Repository, https://github.com/contro1-hq/centcom-langgraph
+Author-email: Contro1 <dev@contro1.com>
+License: MIT
+Keywords: approval,centcom,hitl,human-in-the-loop,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# centcom
+
+Official CENTCOM Python SDK for human-in-the-loop approval requests and webhook verification.
+
+## Install
+
+```bash
+pip install centcom
+```
+
+## Quick Start
+
+```python
+from centcom import CentcomClient, verify_webhook
+
+client = CentcomClient(api_key="cc_live_xxx")
+req = client.create_request(
+    type="approval",
+    context="Order #123 refund request",
+    question="Approve refund?",
+    callback_url="https://your-app.com/centcom-webhook",
+)
+print(req["id"])
+```

centcom-1.0.0/README.md

@@ -0,0 +1,24 @@
+# centcom
+
+Official CENTCOM Python SDK for human-in-the-loop approval requests and webhook verification.
+
+## Install
+
+```bash
+pip install centcom
+```
+
+## Quick Start
+
+```python
+from centcom import CentcomClient, verify_webhook
+
+client = CentcomClient(api_key="cc_live_xxx")
+req = client.create_request(
+    type="approval",
+    context="Order #123 refund request",
+    question="Approve refund?",
+    callback_url="https://your-app.com/centcom-webhook",
+)
+print(req["id"])
+```

centcom-1.0.0/centcom/__init__.py

@@ -0,0 +1,5 @@
+from .client import CentcomClient
+from .webhook import verify_webhook
+
+__all__ = ["CentcomClient", "verify_webhook"]
+__version__ = "1.0.0"

centcom-1.0.0/centcom/client.py

@@ -0,0 +1,171 @@
+"""CENTCOM Python SDK - CentcomClient for creating and managing HITL requests."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://contro1.com/api/centcom/v1"
+DEFAULT_TIMEOUT = 30.0
+
+# States that indicate the request lifecycle is complete or has a response
+TERMINAL_STATES = {
+    "answered", "callback_pending", "callback_delivered",
+    "callback_failed", "closed", "expired", "cancelled",
+}
+
+
+class CentcomError(Exception):
+    """Raised when the CENTCOM API returns an error."""
+
+    def __init__(self, message: str, status_code: int = 0, response: dict | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response or {}
+
+
+class CentcomClient:
+    """
+    Synchronous client for the CENTCOM Human Approval API.
+
+    Usage:
+        client = CentcomClient(api_key="cc_test_xxxx")
+        req = client.create_request(
+            type="yes_no",
+            context="Order #12345 from VIP customer",
+            question="Approve this $2,500 order?",
+            callback_url="https://my-agent.example.com/webhook",
+        )
+        print(req["id"], req["state"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict:
+        res = self._http.request(method, path, **kwargs)
+        data = res.json()
+        if res.status_code >= 400:
+            raise CentcomError(
+                message=data.get("message", f"HTTP {res.status_code}"),
+                status_code=res.status_code,
+                response=data,
+            )
+        return data
+
+    def create_request(
+        self,
+        type: str,
+        context: str,
+        question: str,
+        callback_url: str,
+        priority: str = "normal",
+        required_role: Optional[str] = None,
+        response_schema: Optional[dict] = None,
+        metadata: Optional[dict] = None,
+        sla_minutes: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """
+        Create a new human-in-the-loop request.
+
+        Args:
+            type: Interaction type - "yes_no", "free_text", or "approval"
+            context: Background info displayed to the operator
+            question: The question for the human operator
+            callback_url: Webhook URL for HMAC-signed response delivery
+            priority: "normal" (10 min SLA) or "urgent" (3 min SLA)
+            required_role: Role tag required to answer (e.g. "manager")
+            response_schema: Expected response structure for validation
+            metadata: Arbitrary data returned in the callback
+            sla_minutes: Override SLA timeout
+            idempotency_key: Unique key to prevent duplicate requests
+
+        Returns:
+            dict with the created request data including 'id' and 'state'
+        """
+        body: dict[str, Any] = {
+            "type": type,
+            "context": context,
+            "question": question,
+            "callback_url": callback_url,
+            "priority": priority,
+        }
+        if required_role:
+            body["required_role"] = required_role
+        if response_schema:
+            body["response_schema"] = response_schema
+        if metadata:
+            body["metadata"] = metadata
+        if sla_minutes is not None:
+            body["sla_minutes"] = sla_minutes
+
+        headers = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        return self._request("POST", "/requests", json=body, headers=headers)
+
+    def get_request(self, request_id: str) -> dict:
+        """Get the current state of a request."""
+        return self._request("GET", f"/requests/{request_id}")
+
+    def cancel_request(self, request_id: str) -> dict:
+        """Cancel a pending request (must not yet be answered)."""
+        return self._request("DELETE", f"/requests/{request_id}")
+
+    def wait_for_response(
+        self,
+        request_id: str,
+        interval: float = 3.0,
+        timeout: float = 600.0,
+    ) -> dict:
+        """
+        Poll until the request reaches a terminal state.
+
+        Args:
+            request_id: The request to poll
+            interval: Seconds between polls (default: 3)
+            timeout: Total timeout in seconds (default: 600)
+
+        Returns:
+            The request dict once it has a response or is terminal
+
+        Raises:
+            TimeoutError: If timeout expires before a response
+        """
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            req = self.get_request(request_id)
+            if req.get("state") in TERMINAL_STATES:
+                return req
+            time.sleep(interval)
+        raise TimeoutError(f"Timeout waiting for response on request {request_id}")
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> "CentcomClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

centcom-1.0.0/centcom/webhook.py

@@ -0,0 +1,53 @@
+"""CENTCOM webhook signature verification."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+
+MAX_TIMESTAMP_AGE_SECONDS = 300  # 5 minutes
+
+
+def verify_webhook(
+    raw_body: str | bytes,
+    signature: str,
+    timestamp: str,
+    secret: str,
+) -> bool:
+    """
+    Verify an incoming CENTCOM webhook signature.
+
+    Args:
+        raw_body: The raw HTTP request body (string or bytes)
+        signature: The X-CentCom-Signature header value (hex string)
+        timestamp: The X-CentCom-Timestamp header value (unix seconds)
+        secret: Your organization's webhook signing secret (whsec_xxx)
+
+    Returns:
+        True if the signature is valid and the timestamp is fresh
+    """
+    # Validate timestamp
+    try:
+        ts = int(timestamp)
+    except (ValueError, TypeError):
+        return False
+
+    age = abs(int(time.time()) - ts)
+    if age > MAX_TIMESTAMP_AGE_SECONDS:
+        return False
+
+    # Compute expected signature
+    if isinstance(raw_body, bytes):
+        raw_body = raw_body.decode("utf-8")
+
+    payload = f"{timestamp}.{raw_body}"
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Constant-time comparison
+    return hmac.compare_digest(signature, expected)

centcom-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "centcom"
+version = "1.0.0"
+description = "Official CENTCOM Python SDK for requests and webhook verification"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Contro1", email = "dev@contro1.com" }]
+keywords = ["centcom", "hitl", "human-in-the-loop", "webhook", "approval"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://contro1.com"
+Documentation = "https://contro1.com/docs"
+Repository = "https://github.com/contro1-hq/centcom-langgraph"
+
+[build-system]
+requires = ["hatchling<1.27"]
+build-backend = "hatchling.build"