trodo-python 1.0.0__py3-none-any.whl

trodo/__init__.py

@@ -0,0 +1,134 @@
+"""
+trodo-python — Trodo Analytics SDK for Python
+
+Usage (module-level singleton):
+    import trodo
+    trodo.init(site_id='your-site-id')
+    user = trodo.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+
+Usage (class):
+    from trodo import TrodoClient
+    client = TrodoClient(site_id='your-site-id')
+    user = client.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .client import TrodoClient
+from .user_context import UserContext
+from .managers.group_manager import GroupProfile
+from .types import ApiResult, IdentifyResult, ResetResult, WalletAddressResult
+
+__all__ = [
+    "TrodoClient",
+    "UserContext",
+    "GroupProfile",
+    "init",
+    "for_user",
+    "track",
+    "identify",
+    "wallet_address",
+    "reset",
+    "enable_auto_events",
+    "disable_auto_events",
+    "flush",
+    "shutdown",
+]
+
+# ============================================================================
+# Singleton convenience API
+# ============================================================================
+
+_client: Optional[TrodoClient] = None
+
+
+def _get_client() -> TrodoClient:
+    if _client is None:
+        raise RuntimeError(
+            "trodo-python: Call trodo.init(site_id=...) before using the SDK."
+        )
+    return _client
+
+
+def init(
+    site_id: str,
+    api_base: str = "https://sdkapi.trodo.ai",
+    timeout: int = 10,
+    retries: int = 2,
+    batch_enabled: bool = False,
+    batch_size: int = 50,
+    batch_flush_interval: float = 5.0,
+    auto_events: bool = False,
+    on_error: Optional[Any] = None,
+    debug: bool = False,
+) -> TrodoClient:
+    """Initialise the singleton SDK instance."""
+    global _client
+    _client = TrodoClient(
+        site_id=site_id,
+        api_base=api_base,
+        timeout=timeout,
+        retries=retries,
+        batch_enabled=batch_enabled,
+        batch_size=batch_size,
+        batch_flush_interval=batch_flush_interval,
+        auto_events=auto_events,
+        on_error=on_error,
+        debug=debug,
+    )
+    return _client
+
+
+def for_user(
+    distinct_id: str,
+    session_id: Optional[str] = None,
+) -> UserContext:
+    """Return a UserContext bound to the given distinctId."""
+    return _get_client().for_user(distinct_id, session_id)
+
+
+def track(
+    distinct_id: str,
+    event_name: str,
+    properties: Optional[Dict[str, Any]] = None,
+    category: str = "custom",
+) -> None:
+    """Track an event for a user (direct-call pattern)."""
+    _get_client().track(distinct_id, event_name, properties, category)
+
+
+def identify(distinct_id: str, identify_id: str) -> IdentifyResult:
+    """Alias a user's distinctId to an external identifier."""
+    return _get_client().identify(distinct_id, identify_id)
+
+
+def wallet_address(distinct_id: str, wallet_addr: str) -> WalletAddressResult:
+    """Associate a wallet address with a user."""
+    return _get_client().wallet_address(distinct_id, wallet_addr)
+
+
+def reset(distinct_id: str) -> ResetResult:
+    """Reset a user's session."""
+    return _get_client().reset(distinct_id)
+
+
+def enable_auto_events() -> None:
+    _get_client().enable_auto_events()
+
+
+def disable_auto_events() -> None:
+    _get_client().disable_auto_events()
+
+
+def flush() -> None:
+    """Flush any queued batch events."""
+    _get_client().flush()
+
+
+def shutdown() -> None:
+    """Flush, stop timers, and disable auto events."""
+    _get_client().shutdown()

trodo/api/async_client.py

@@ -0,0 +1,96 @@
+"""Async HTTP client using httpx (optional dependency)."""
+
+from __future__ import annotations
+
+import sys
+import asyncio
+from typing import Any, Callable, Dict, Optional
+
+from ..types import ApiResult, EventPayload
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        api_base: str,
+        site_id: str,
+        timeout: int = 10,
+        retries: int = 2,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        debug: bool = False,
+    ) -> None:
+        try:
+            import httpx  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "trodo-python async support requires httpx: pip install trodo-python[async]"
+            )
+
+        self.api_base = api_base.rstrip("/")
+        self.site_id = site_id
+        self.timeout = timeout
+        self.retries = retries
+        self.on_error = on_error
+        self.debug = debug
+
+    def _log(self, *args: Any) -> None:
+        if self.debug:
+            sys.stderr.write(f"[trodo-python-async] {' '.join(str(a) for a in args)}\n")
+
+    async def _request(
+        self, path: str, body: Dict[str, Any], attempt: int = 0
+    ) -> ApiResult:
+        import httpx
+
+        url = f"{self.api_base}{path}"
+        self._log(f"POST {url}")
+        headers = {
+            "Content-Type": "application/json",
+            "X-Trodo-Site-Id": self.site_id,
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(url, json=body, headers=headers)
+            if resp.status_code >= 500 and attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s")
+                await asyncio.sleep(delay)
+                return await self._request(path, body, attempt + 1)
+            try:
+                return resp.json()
+            except Exception:
+                return {}
+        except Exception as exc:
+            if attempt < self.retries:
+                await asyncio.sleep(2 ** attempt)
+                return await self._request(path, body, attempt + 1)
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {}
+
+    async def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/track", {"sessionData": session_data})
+
+    async def post_event(self, event: EventPayload) -> ApiResult:
+        return await self._request("/api/events", event.to_dict())
+
+    async def post_bulk_events(self, events: list) -> ApiResult:
+        return await self._request(
+            "/api/events/bulk", {"events": [e.to_dict() for e in events]}
+        )
+
+    async def post_identify(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/identify", payload)
+
+    async def post_wallet_address(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/wallet-address", payload)
+
+    async def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/reset", payload)
+
+    async def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)
+
+    async def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)

trodo/api/endpoints.py

@@ -0,0 +1,20 @@
+TRACK = "/api/sdk/track"
+EVENTS = "/api/events"
+EVENTS_BULK = "/api/events/bulk"
+IDENTIFY = "/api/sdk/identify"
+WALLET_ADDRESS = "/api/sdk/wallet-address"
+RESET = "/api/sdk/reset"
+PEOPLE_SET = "/api/sdk/people/set"
+PEOPLE_SET_ONCE = "/api/sdk/people/set_once"
+PEOPLE_UNSET = "/api/sdk/people/unset"
+PEOPLE_INCREMENT = "/api/sdk/people/increment"
+PEOPLE_APPEND = "/api/sdk/people/append"
+PEOPLE_UNION = "/api/sdk/people/union"
+PEOPLE_REMOVE = "/api/sdk/people/remove"
+PEOPLE_TRACK_CHARGE = "/api/sdk/people/track_charge"
+PEOPLE_CLEAR_CHARGES = "/api/sdk/people/clear_charges"
+PEOPLE_DELETE_USER = "/api/sdk/people/delete_user"
+GROUPS_SET = "/api/sdk/groups/set_group"
+GROUPS_ADD = "/api/sdk/groups/add_group"
+GROUPS_REMOVE = "/api/sdk/groups/remove_group"
+GROUPS_PROFILE = "/api/sdk/groups/profile"

trodo/api/http_client.py

@@ -0,0 +1,87 @@
+"""Synchronous HTTP client using requests."""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any, Callable, Dict, Optional
+
+import requests
+
+from ..types import ApiResult, EventPayload
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_base: str,
+        site_id: str,
+        timeout: int = 10,
+        retries: int = 2,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        debug: bool = False,
+    ) -> None:
+        self.api_base = api_base.rstrip("/")
+        self.site_id = site_id
+        self.timeout = timeout
+        self.retries = retries
+        self.on_error = on_error
+        self.debug = debug
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Content-Type": "application/json",
+            "X-Trodo-Site-Id": self.site_id,
+        })
+
+    def _log(self, *args: Any) -> None:
+        if self.debug:
+            sys.stderr.write(f"[trodo-python] {' '.join(str(a) for a in args)}\n")
+
+    def _request(self, path: str, body: Dict[str, Any], attempt: int = 0) -> ApiResult:
+        url = f"{self.api_base}{path}"
+        self._log(f"POST {url}")
+        try:
+            resp = self._session.post(url, json=body, timeout=self.timeout)
+            if resp.status_code >= 500 and attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s (status {resp.status_code})")
+                time.sleep(delay)
+                return self._request(path, body, attempt + 1)
+            try:
+                return resp.json()
+            except Exception:
+                return {}
+        except Exception as exc:
+            if attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s (network error)")
+                time.sleep(delay)
+                return self._request(path, body, attempt + 1)
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {}
+
+    def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/track", {"sessionData": session_data})
+
+    def post_event(self, event: EventPayload) -> ApiResult:
+        return self._request("/api/events", event.to_dict())
+
+    def post_bulk_events(self, events: list) -> ApiResult:
+        return self._request("/api/events/bulk", {"events": [e.to_dict() for e in events]})
+
+    def post_identify(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/identify", payload)
+
+    def post_wallet_address(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/wallet-address", payload)
+
+    def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/reset", payload)
+
+    def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return self._request(path, payload)
+
+    def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return self._request(path, payload)

trodo/auto/auto_event_manager.py

@@ -0,0 +1,134 @@
+"""Auto event manager — captures unhandled Python exceptions as server_error events."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import traceback
+from datetime import datetime, timezone
+from typing import Any, Optional, TYPE_CHECKING
+
+from ..types import EventPayload
+
+if TYPE_CHECKING:
+    from ..session.session_manager import SessionManager
+    from ..api.http_client import HttpClient
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class AutoEventManager:
+    def __init__(
+        self,
+        site_id: str,
+        http_client: "HttpClient",
+        session_manager: "SessionManager",
+    ) -> None:
+        self._site_id = site_id
+        self._http = http_client
+        self._session_manager = session_manager
+        self._enabled = False
+        self._prev_excepthook: Any = None
+        self._prev_thread_excepthook: Any = None
+
+    def enable(self) -> None:
+        if self._enabled:
+            return
+        self._enabled = True
+
+        # Wrap sys.excepthook
+        self._prev_excepthook = sys.excepthook
+
+        def _excepthook(exc_type, exc_value, exc_tb):
+            self._track_error(
+                exc_type.__name__ if exc_type else "Exception",
+                str(exc_value),
+                "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+            )
+            if self._prev_excepthook:
+                self._prev_excepthook(exc_type, exc_value, exc_tb)
+
+        sys.excepthook = _excepthook
+
+        # Wrap threading.excepthook (Python 3.8+)
+        if hasattr(threading, "excepthook"):
+            self._prev_thread_excepthook = threading.excepthook
+
+            def _thread_excepthook(args):
+                self._track_error(
+                    args.exc_type.__name__ if args.exc_type else "ThreadException",
+                    str(args.exc_value),
+                    "".join(
+                        traceback.format_exception(
+                            args.exc_type, args.exc_value, args.exc_tb
+                        )
+                    ),
+                )
+                if self._prev_thread_excepthook:
+                    self._prev_thread_excepthook(args)
+
+            threading.excepthook = _thread_excepthook
+
+    def disable(self) -> None:
+        if not self._enabled:
+            return
+        self._enabled = False
+
+        if self._prev_excepthook is not None:
+            sys.excepthook = self._prev_excepthook
+            self._prev_excepthook = None
+
+        if hasattr(threading, "excepthook") and self._prev_thread_excepthook is not None:
+            threading.excepthook = self._prev_thread_excepthook
+            self._prev_thread_excepthook = None
+
+    def is_enabled(self) -> bool:
+        return self._enabled
+
+    def track_error(
+        self,
+        error: Exception,
+        error_type: Optional[str] = None,
+        severity: str = "error",
+        distinct_id: str = "server_global",
+    ) -> None:
+        self._track_error(
+            error_type or type(error).__name__,
+            str(error),
+            traceback.format_exc() or repr(error),
+            severity=severity,
+            distinct_id=distinct_id,
+        )
+
+    def _track_error(
+        self,
+        error_type: str,
+        message: str,
+        stack: str,
+        severity: str = "critical",
+        distinct_id: str = "server_global",
+    ) -> None:
+        try:
+            session = self._session_manager.get_or_create(distinct_id, self._site_id)
+            self._session_manager.ensure_confirmed(session, self._http)
+
+            event = EventPayload(
+                event_type="auto",
+                event_name="server_error",
+                event_category="error",
+                session_id=session.session_id,
+                user_id=session.distinct_id,
+                custom_properties={
+                    "error_type": error_type,
+                    "message": message,
+                    "stack": stack,
+                    "runtime": "python",
+                    "severity": severity,
+                    "timestamp": _now_iso(),
+                },
+            )
+            self._http.post_event(event)
+        except Exception:
+            pass  # Never let error tracking crash the process

trodo/client.py

@@ -0,0 +1,195 @@
+"""TrodoClient — main SDK class for Python."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .api.http_client import HttpClient
+from .session.session_manager import SessionManager
+from .managers.people_manager import PeopleManager
+from .managers.group_manager import GroupManager, GroupProfile
+from .queue.event_queue import EventQueue
+from .queue.batch_flusher import BatchFlusher
+from .auto.auto_event_manager import AutoEventManager
+from .user_context import UserContext
+from .types import (
+    ApiResult,
+    IdentifyResult,
+    ResetResult,
+    WalletAddressResult,
+)
+
+
+class TrodoClient:
+    def __init__(
+        self,
+        site_id: str,
+        api_base: str = "https://sdkapi.trodo.ai",
+        timeout: int = 10,
+        retries: int = 2,
+        batch_enabled: bool = False,
+        batch_size: int = 50,
+        batch_flush_interval: float = 5.0,
+        auto_events: bool = False,
+        on_error: Optional[Any] = None,
+        debug: bool = False,
+    ) -> None:
+        if not site_id:
+            raise ValueError("trodo-python: site_id is required")
+
+        self.site_id = site_id
+
+        self._http = HttpClient(
+            api_base=api_base,
+            site_id=site_id,
+            timeout=timeout,
+            retries=retries,
+            on_error=on_error,
+            debug=debug,
+        )
+
+        self._session_manager = SessionManager()
+
+        if batch_enabled:
+            self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
+            self._batch_flusher: Optional[BatchFlusher] = BatchFlusher(
+                self._event_queue, self._http, batch_flush_interval
+            )
+            self._batch_flusher.start()
+        else:
+            self._event_queue = None
+            self._batch_flusher = None
+
+        self._auto_event_manager = AutoEventManager(
+            site_id, self._http, self._session_manager
+        )
+
+        if auto_events:
+            self._auto_event_manager.enable()
+
+        self._user_context_cache: Dict[str, UserContext] = {}
+
+    # --------------------------------------------------------------------------
+    # Primary pattern: for_user()
+    # --------------------------------------------------------------------------
+
+    def for_user(
+        self,
+        distinct_id: str,
+        session_id: Optional[str] = None,
+    ) -> UserContext:
+        if distinct_id in self._user_context_cache:
+            return self._user_context_cache[distinct_id]
+
+        ctx = UserContext(
+            distinct_id=distinct_id,
+            site_id=self.site_id,
+            http_client=self._http,
+            session_manager=self._session_manager,
+            event_queue=self._event_queue,
+            batch_flusher=self._batch_flusher,
+            auto_event_manager=self._auto_event_manager,
+            session_id=session_id,
+        )
+        self._user_context_cache[distinct_id] = ctx
+        return ctx
+
+    # --------------------------------------------------------------------------
+    # Direct-call pattern (distinct_id as first arg)
+    # --------------------------------------------------------------------------
+
+    def track(
+        self,
+        distinct_id: str,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        category: str = "custom",
+    ) -> None:
+        self.for_user(distinct_id).track(event_name, properties, category)
+
+    def identify(self, distinct_id: str, identify_id: str) -> IdentifyResult:
+        return self.for_user(distinct_id).identify(identify_id)
+
+    def wallet_address(self, distinct_id: str, wallet_addr: str) -> WalletAddressResult:
+        return self.for_user(distinct_id).wallet_address(wallet_addr)
+
+    def reset(self, distinct_id: str) -> ResetResult:
+        self._user_context_cache.pop(distinct_id, None)
+        return self.for_user(distinct_id).reset()
+
+    # People (direct)
+    def people_set(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.set(properties)
+
+    def people_set_once(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.set_once(properties)
+
+    def people_unset(self, distinct_id: str, keys: Union[str, List[str]]) -> ApiResult:
+        return self.for_user(distinct_id).people.unset(keys)
+
+    def people_increment(self, distinct_id: str, key: str, amount: float = 1) -> ApiResult:
+        return self.for_user(distinct_id).people.increment(key, amount)
+
+    def people_append(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.append(key, values)
+
+    def people_union(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.union(key, values)
+
+    def people_remove(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.remove(key, values)
+
+    def people_track_charge(
+        self,
+        distinct_id: str,
+        amount: float,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> ApiResult:
+        return self.for_user(distinct_id).people.track_charge(amount, properties)
+
+    def people_clear_charges(self, distinct_id: str) -> ApiResult:
+        return self.for_user(distinct_id).people.clear_charges()
+
+    def people_delete_user(self, distinct_id: str) -> ApiResult:
+        return self.for_user(distinct_id).people.delete_user()
+
+    # Groups (direct)
+    def set_group(
+        self, distinct_id: str, group_key: str, group_id: Union[str, List[str]]
+    ) -> ApiResult:
+        return self.for_user(distinct_id).set_group(group_key, group_id)
+
+    def add_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
+        return self.for_user(distinct_id).add_group(group_key, group_id)
+
+    def remove_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
+        return self.for_user(distinct_id).remove_group(group_key, group_id)
+
+    def get_group(
+        self, distinct_id: str, group_key: str, group_id: str
+    ) -> GroupProfile:
+        return self.for_user(distinct_id).get_group(group_key, group_id)
+
+    # --------------------------------------------------------------------------
+    # Auto events
+    # --------------------------------------------------------------------------
+
+    def enable_auto_events(self) -> None:
+        self._auto_event_manager.enable()
+
+    def disable_auto_events(self) -> None:
+        self._auto_event_manager.disable()
+
+    # --------------------------------------------------------------------------
+    # Lifecycle
+    # --------------------------------------------------------------------------
+
+    def flush(self) -> None:
+        if self._batch_flusher:
+            self._batch_flusher.flush()
+
+    def shutdown(self) -> None:
+        self._auto_event_manager.disable()
+        if self._batch_flusher:
+            self._batch_flusher.stop()
+            self._batch_flusher.flush()