vortex-python-sdk 0.9.4__tar.gz → 0.10.0__tar.gz

{vortex_python_sdk-0.9.4/src/vortex_python_sdk.egg-info → vortex_python_sdk-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.9.4
+Version: 0.10.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -295,6 +295,53 @@ ruff check src/ tests/
 mypy src/
 ```
 
+## Webhooks
+
+The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+
+### Setup
+
+```python
+import os
+from vortex_sdk import VortexWebhooks, is_webhook_event, is_analytics_event
+
+webhooks = VortexWebhooks(secret=os.environ["VORTEX_WEBHOOK_SECRET"])
+```
+
+### Verifying and Parsing Events
+
+```python
+# In your HTTP handler (Flask example):
+@app.route("/webhooks/vortex", methods=["POST"])
+def handle_webhook():
+    payload = request.get_data(as_text=True)
+    signature = request.headers.get("X-Vortex-Signature", "")
+
+    try:
+        event = webhooks.construct_event(payload, signature)
+    except VortexWebhookSignatureError:
+        return "Invalid signature", 400
+
+    if is_webhook_event(event.__dict__):
+        print(f"Webhook event: {event.type}")
+    elif is_analytics_event(event.__dict__):
+        print(f"Analytics event: {event.name}")
+
+    return "OK", 200
+```
+
+### Event Types
+
+Webhook event types are available as the `WebhookEventType` enum:
+
+```python
+from vortex_sdk import WebhookEventType
+
+if event.type == WebhookEventType.INVITATION_ACCEPTED:
+    # Handle invitation accepted
+    pass
+```
+
 ## License
 
 MIT

{vortex_python_sdk-0.9.4 → vortex_python_sdk-0.10.0}/README.md

@@ -257,6 +257,53 @@ ruff check src/ tests/
 mypy src/
 ```
 
+## Webhooks
+
+The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+
+### Setup
+
+```python
+import os
+from vortex_sdk import VortexWebhooks, is_webhook_event, is_analytics_event
+
+webhooks = VortexWebhooks(secret=os.environ["VORTEX_WEBHOOK_SECRET"])
+```
+
+### Verifying and Parsing Events
+
+```python
+# In your HTTP handler (Flask example):
+@app.route("/webhooks/vortex", methods=["POST"])
+def handle_webhook():
+    payload = request.get_data(as_text=True)
+    signature = request.headers.get("X-Vortex-Signature", "")
+
+    try:
+        event = webhooks.construct_event(payload, signature)
+    except VortexWebhookSignatureError:
+        return "Invalid signature", 400
+
+    if is_webhook_event(event.__dict__):
+        print(f"Webhook event: {event.type}")
+    elif is_analytics_event(event.__dict__):
+        print(f"Analytics event: {event.name}")
+
+    return "OK", 200
+```
+
+### Event Types
+
+Webhook event types are available as the `WebhookEventType` enum:
+
+```python
+from vortex_sdk import WebhookEventType
+
+if event.type == WebhookEventType.INVITATION_ACCEPTED:
+    # Handle invitation accepted
+    pass
+```
+
 ## License
 
 MIT

{vortex_python_sdk-0.9.4 → vortex_python_sdk-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex-python-sdk"
-version = "0.9.4"
+version = "0.10.0"
 description = "Vortex Python SDK for invitation management and JWT generation"
 authors = [{name = "TeamVortexSoftware", email = "support@vortexsoftware.com"}]
 readme = "README.md"

{vortex_python_sdk-0.9.4 → vortex_python_sdk-0.10.0/src/vortex_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex-python-sdk
-Version: 0.9.4
+Version: 0.10.0
 Summary: Vortex Python SDK for invitation management and JWT generation
 Author-email: TeamVortexSoftware <support@vortexsoftware.com>
 License-Expression: MIT
@@ -295,6 +295,53 @@ ruff check src/ tests/
 mypy src/
 ```
 
+## Webhooks
+
+The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+
+### Setup
+
+```python
+import os
+from vortex_sdk import VortexWebhooks, is_webhook_event, is_analytics_event
+
+webhooks = VortexWebhooks(secret=os.environ["VORTEX_WEBHOOK_SECRET"])
+```
+
+### Verifying and Parsing Events
+
+```python
+# In your HTTP handler (Flask example):
+@app.route("/webhooks/vortex", methods=["POST"])
+def handle_webhook():
+    payload = request.get_data(as_text=True)
+    signature = request.headers.get("X-Vortex-Signature", "")
+
+    try:
+        event = webhooks.construct_event(payload, signature)
+    except VortexWebhookSignatureError:
+        return "Invalid signature", 400
+
+    if is_webhook_event(event.__dict__):
+        print(f"Webhook event: {event.type}")
+    elif is_analytics_event(event.__dict__):
+        print(f"Analytics event: {event.name}")
+
+    return "OK", 200
+```
+
+### Event Types
+
+Webhook event types are available as the `WebhookEventType` enum:
+
+```python
+from vortex_sdk import WebhookEventType
+
+if event.type == WebhookEventType.INVITATION_ACCEPTED:
+    # Handle invitation accepted
+    pass
+```
+
 ## License
 
 MIT

{vortex_python_sdk-0.9.4 → vortex_python_sdk-0.10.0}/src/vortex_python_sdk.egg-info/SOURCES.txt

@@ -11,4 +11,7 @@ src/vortex_python_sdk.egg-info/top_level.txt
 src/vortex_sdk/__init__.py
 src/vortex_sdk/py.typed
 src/vortex_sdk/types.py
-src/vortex_sdk/vortex.py
+src/vortex_sdk/vortex.py
+src/vortex_sdk/webhook_types.py
+src/vortex_sdk/webhooks.py
+tests/test_webhooks.py

{vortex_python_sdk-0.9.4 → vortex_python_sdk-0.10.0}/src/vortex_sdk/__init__.py

@@ -28,8 +28,18 @@ from .types import (
     VortexApiError,
 )
 from .vortex import Vortex
+from .webhook_types import (
+    AnalyticsEventType,
+    VortexAnalyticsEvent,
+    VortexEvent,
+    VortexWebhookEvent,
+    WebhookEventType,
+    is_analytics_event,
+    is_webhook_event,
+)
+from .webhooks import VortexWebhookSignatureError, VortexWebhooks
 
-__version__ = "0.9.2"
+__version__ = "0.10.0"
 __author__ = "TeamVortexSoftware"
 __email__ = "support@vortexsoftware.com"
 
@@ -56,4 +66,13 @@ __all__ = [
     "ApiResponseJson",
     "ApiRequestBody",
     "VortexApiError",
+    "VortexWebhooks",
+    "VortexWebhookSignatureError",
+    "VortexWebhookEvent",
+    "VortexAnalyticsEvent",
+    "VortexEvent",
+    "WebhookEventType",
+    "AnalyticsEventType",
+    "is_webhook_event",
+    "is_analytics_event",
 ]

vortex_python_sdk-0.10.0/src/vortex_sdk/webhook_types.py

@@ -0,0 +1,117 @@
+"""
+Vortex Webhook Types
+
+Type definitions for webhook event handling.
+These mirror the server-side types but are kept independent
+so the SDK has no internal dependencies.
+
+@see DEV-1769
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+# ─── Webhook Event Type Constants ──────────────────────────────────────
+
+
+class WebhookEventType(str, Enum):
+    """Webhook event types for Vortex state changes."""
+
+    # Invitation Lifecycle
+    INVITATION_CREATED = "invitation.created"
+    INVITATION_ACCEPTED = "invitation.accepted"
+    INVITATION_DEACTIVATED = "invitation.deactivated"
+    INVITATION_EMAIL_DELIVERED = "invitation.email.delivered"
+    INVITATION_EMAIL_BOUNCED = "invitation.email.bounced"
+    INVITATION_EMAIL_OPENED = "invitation.email.opened"
+    INVITATION_LINK_CLICKED = "invitation.link.clicked"
+    INVITATION_REMINDER_SENT = "invitation.reminder.sent"
+
+    # Deployment Lifecycle
+    DEPLOYMENT_CREATED = "deployment.created"
+    DEPLOYMENT_DEACTIVATED = "deployment.deactivated"
+
+    # A/B Testing
+    ABTEST_STARTED = "abtest.started"
+    ABTEST_WINNER_DECLARED = "abtest.winner_declared"
+
+    # Member/Group
+    MEMBER_CREATED = "member.created"
+    GROUP_MEMBER_ADDED = "group.member.added"
+
+    # Email
+    EMAIL_COMPLAINED = "email.complained"
+
+
+class AnalyticsEventType(str, Enum):
+    """Analytics event types for behavioral telemetry."""
+
+    WIDGET_LOADED = "widget_loaded"
+    INVITATION_SENT = "invitation_sent"
+    INVITATION_CLICKED = "invitation_clicked"
+    INVITATION_ACCEPTED = "invitation_accepted"
+    SHARE_TRIGGERED = "share_triggered"
+
+
+# ─── Webhook Event Payload ─────────────────────────────────────────────
+
+
+class VortexWebhookEvent(BaseModel):
+    """A Vortex webhook event representing a server-side state change."""
+
+    id: str
+    type: str
+    timestamp: str
+    account_id: str = Field(alias="accountId")
+    environment_id: Optional[str] = Field(None, alias="environmentId")
+    source_table: str = Field(alias="sourceTable")
+    operation: str  # "insert" | "update" | "delete"
+    data: Dict[str, Any]
+
+    class Config:
+        populate_by_name = True
+
+
+# ─── Analytics Event Payload ───────────────────────────────────────────
+
+
+class VortexAnalyticsEvent(BaseModel):
+    """An analytics event representing client-side behavioral telemetry."""
+
+    id: str
+    name: str
+    account_id: str = Field(alias="accountId")
+    organization_id: str = Field(alias="organizationId")
+    project_id: str = Field(alias="projectId")
+    environment_id: str = Field(alias="environmentId")
+    deployment_id: Optional[str] = Field(None, alias="deploymentId")
+    widget_configuration_id: Optional[str] = Field(
+        None, alias="widgetConfigurationId"
+    )
+    foreign_user_id: Optional[str] = Field(None, alias="foreignUserId")
+    session_id: Optional[str] = Field(None, alias="sessionId")
+    payload: Optional[Dict[str, Any]] = None
+    platform: Optional[str] = None
+    segmentation: Optional[str] = None
+    timestamp: str
+
+    class Config:
+        populate_by_name = True
+
+
+# ─── Union & Discriminator ─────────────────────────────────────────────
+
+VortexEvent = Union[VortexWebhookEvent, VortexAnalyticsEvent]
+
+
+def is_webhook_event(event: Dict[str, Any]) -> bool:
+    """Returns True if the event dict is a webhook event (has 'type', no 'name')."""
+    return "type" in event and "name" not in event
+
+
+def is_analytics_event(event: Dict[str, Any]) -> bool:
+    """Returns True if the event dict is an analytics event (has 'name')."""
+    return "name" in event

vortex_python_sdk-0.10.0/src/vortex_sdk/webhooks.py

@@ -0,0 +1,120 @@
+"""
+Vortex Webhooks
+
+Core webhook verification and parsing for the Vortex Python SDK.
+
+Example::
+
+    from vortex_sdk import VortexWebhooks
+
+    webhooks = VortexWebhooks(secret=os.environ["VORTEX_WEBHOOK_SECRET"])
+
+    # In any HTTP handler:
+    event = webhooks.construct_event(raw_body, signature_header)
+
+@see DEV-1769
+"""
+
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Union
+
+from .webhook_types import (
+    VortexAnalyticsEvent,
+    VortexEvent,
+    VortexWebhookEvent,
+    is_analytics_event,
+    is_webhook_event,
+)
+
+
+class VortexWebhookSignatureError(Exception):
+    """Raised when webhook signature verification fails."""
+
+    pass
+
+
+class VortexWebhooks:
+    """
+    Core webhook verification and parsing.
+
+    This class is framework-agnostic — use it directly or with
+    framework-specific integrations (Flask, Django, FastAPI).
+
+    Args:
+        secret: The webhook signing secret from your Vortex dashboard.
+
+    Example::
+
+        from vortex_sdk import VortexWebhooks
+
+        webhooks = VortexWebhooks(secret=os.environ["VORTEX_WEBHOOK_SECRET"])
+        event = webhooks.construct_event(request.body, request.headers["X-Vortex-Signature"])
+    """
+
+    def __init__(self, secret: str) -> None:
+        if not secret:
+            raise ValueError("VortexWebhooks requires a secret")
+        self._secret = secret
+
+    def verify_signature(self, payload: Union[str, bytes], signature: str) -> bool:
+        """
+        Verify the HMAC-SHA256 signature of an incoming webhook payload.
+
+        Args:
+            payload: The raw request body (str or bytes).
+            signature: The value of the ``X-Vortex-Signature`` header.
+
+        Returns:
+            ``True`` if the signature is valid.
+        """
+        if not signature:
+            return False
+
+        if isinstance(payload, str):
+            payload = payload.encode("utf-8")
+
+        expected = hmac.new(
+            self._secret.encode("utf-8"),
+            payload,
+            hashlib.sha256,
+        ).hexdigest()
+
+        # Timing-safe comparison to prevent timing attacks
+        return hmac.compare_digest(signature, expected)
+
+    def construct_event(
+        self, payload: Union[str, bytes], signature: str
+    ) -> VortexEvent:
+        """
+        Verify and parse an incoming webhook payload.
+
+        Args:
+            payload: The raw request body (str or bytes). Must be the raw body,
+                not a parsed dict — signature verification requires the exact
+                bytes that were signed.
+            signature: The value of the ``X-Vortex-Signature`` header.
+
+        Returns:
+            A :class:`VortexWebhookEvent` or :class:`VortexAnalyticsEvent`.
+
+        Raises:
+            VortexWebhookSignatureError: If the signature is invalid.
+        """
+        if not self.verify_signature(payload, signature):
+            raise VortexWebhookSignatureError(
+                "Webhook signature verification failed. Ensure you are using "
+                "the raw request body and the correct signing secret."
+            )
+
+        body = payload if isinstance(payload, str) else payload.decode("utf-8")
+        parsed: Dict[str, Any] = json.loads(body)
+
+        if is_webhook_event(parsed):
+            return VortexWebhookEvent(**parsed)
+        elif is_analytics_event(parsed):
+            return VortexAnalyticsEvent(**parsed)
+        else:
+            # Return as webhook event by default
+            return VortexWebhookEvent(**parsed)

vortex_python_sdk-0.10.0/tests/test_webhooks.py

@@ -0,0 +1,118 @@
+"""Tests for Vortex webhook signature verification and event construction."""
+
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from vortex_sdk import (
+    VortexAnalyticsEvent,
+    VortexWebhookEvent,
+    VortexWebhookSignatureError,
+    VortexWebhooks,
+    is_analytics_event,
+    is_webhook_event,
+)
+
+
+SECRET = "whsec_test_secret_123"
+
+WEBHOOK_EVENT_PAYLOAD = json.dumps(
+    {
+        "id": "evt_123",
+        "type": "invitation.accepted",
+        "timestamp": "2025-01-15T12:00:00.000Z",
+        "accountId": "acc_123",
+        "environmentId": "env_456",
+        "sourceTable": "invitations",
+        "operation": "update",
+        "data": {"invitationId": "inv_789", "targetEmail": "user@example.com"},
+    }
+)
+
+ANALYTICS_EVENT_PAYLOAD = json.dumps(
+    {
+        "id": "evt_456",
+        "name": "widget_loaded",
+        "accountId": "acc_123",
+        "organizationId": "org_123",
+        "projectId": "proj_123",
+        "environmentId": "env_456",
+        "deploymentId": None,
+        "widgetConfigurationId": "wc_123",
+        "foreignUserId": "user_123",
+        "sessionId": "sess_123",
+        "payload": {"page": "/dashboard"},
+        "platform": "web",
+        "segmentation": None,
+        "timestamp": "2025-01-15T12:00:00.000Z",
+    }
+)
+
+
+def _sign(payload: str, secret: str = SECRET) -> str:
+    return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+class TestVortexWebhooks:
+    def test_constructor_requires_secret(self) -> None:
+        with pytest.raises(ValueError, match="requires a secret"):
+            VortexWebhooks(secret="")
+
+    def test_verify_signature_valid(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        sig = _sign(WEBHOOK_EVENT_PAYLOAD)
+        assert wh.verify_signature(WEBHOOK_EVENT_PAYLOAD, sig) is True
+
+    def test_verify_signature_invalid(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        assert wh.verify_signature(WEBHOOK_EVENT_PAYLOAD, "bad_signature") is False
+
+    def test_verify_signature_empty(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        assert wh.verify_signature(WEBHOOK_EVENT_PAYLOAD, "") is False
+
+    def test_verify_signature_wrong_secret(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        sig = _sign(WEBHOOK_EVENT_PAYLOAD, "wrong_secret")
+        assert wh.verify_signature(WEBHOOK_EVENT_PAYLOAD, sig) is False
+
+    def test_verify_signature_bytes_payload(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        sig = _sign(WEBHOOK_EVENT_PAYLOAD)
+        assert wh.verify_signature(WEBHOOK_EVENT_PAYLOAD.encode("utf-8"), sig) is True
+
+    def test_construct_webhook_event(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        sig = _sign(WEBHOOK_EVENT_PAYLOAD)
+        event = wh.construct_event(WEBHOOK_EVENT_PAYLOAD, sig)
+        assert isinstance(event, VortexWebhookEvent)
+        assert event.id == "evt_123"
+        assert event.type == "invitation.accepted"
+        assert event.account_id == "acc_123"
+        assert event.data["targetEmail"] == "user@example.com"
+
+    def test_construct_analytics_event(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        sig = _sign(ANALYTICS_EVENT_PAYLOAD)
+        event = wh.construct_event(ANALYTICS_EVENT_PAYLOAD, sig)
+        assert isinstance(event, VortexAnalyticsEvent)
+        assert event.id == "evt_456"
+        assert event.name == "widget_loaded"
+        assert event.account_id == "acc_123"
+
+    def test_construct_event_bad_signature(self) -> None:
+        wh = VortexWebhooks(secret=SECRET)
+        with pytest.raises(VortexWebhookSignatureError):
+            wh.construct_event(WEBHOOK_EVENT_PAYLOAD, "bad_sig")
+
+
+class TestTypeGuards:
+    def test_is_webhook_event(self) -> None:
+        assert is_webhook_event({"type": "invitation.accepted", "id": "1"}) is True
+        assert is_webhook_event({"name": "widget_loaded", "id": "1"}) is False
+
+    def test_is_analytics_event(self) -> None:
+        assert is_analytics_event({"name": "widget_loaded", "id": "1"}) is True
+        assert is_analytics_event({"type": "invitation.accepted", "id": "1"}) is False