trodo-python 1.0.0__py3-none-any.whl

trodo/managers/group_manager.py

@@ -0,0 +1,106 @@
+"""Group management methods and GroupProfile proxy."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from ..api import endpoints
+from ..types import ApiResult
+
+
+class GroupProfile:
+    def __init__(
+        self,
+        http_client: object,
+        site_id: str,
+        distinct_id: str,
+        group_key: str,
+        group_id: str,
+    ) -> None:
+        self._http = http_client
+        self._site_id = site_id
+        self._distinct_id = distinct_id
+        self._group_key = group_key
+        self._group_id = group_id
+
+    def _base(self) -> Dict[str, Any]:
+        return {
+            "siteId": self._site_id,
+            "userId": self._distinct_id,
+            "groupKey": self._group_key,
+            "groupId": self._group_id,
+        }
+
+    def _call(self, method: str, extra: Optional[Dict[str, Any]] = None) -> ApiResult:
+        payload = {**self._base(), **(extra or {})}
+        return self._http.post_group(  # type: ignore[attr-defined]
+            f"{endpoints.GROUPS_PROFILE}/{method}", payload
+        )
+
+    def set(self, properties: Dict[str, Any]) -> ApiResult:
+        return self._call("set", {"properties": properties})
+
+    def set_once(self, properties: Dict[str, Any]) -> ApiResult:
+        return self._call("set_once", {"properties": properties})
+
+    def union(self, list_name: str, values: List[Any]) -> ApiResult:
+        return self._call("union", {"listName": list_name, "values": values})
+
+    def remove(self, list_name: str, value: Any) -> ApiResult:
+        return self._call("remove", {"listName": list_name, "value": value})
+
+    def unset(self, property: str) -> ApiResult:
+        return self._call("unset", {"property": property})
+
+    def increment(self, property: str, value: float = 1) -> ApiResult:
+        return self._call("increment", {"property": property, "value": value})
+
+    def append(self, property: str, value: Any) -> ApiResult:
+        return self._call("append", {"property": property, "value": value})
+
+    def delete(self) -> ApiResult:
+        return self._call("delete")
+
+
+class GroupManager:
+    def __init__(
+        self,
+        http_client: object,
+        site_id: str,
+        get_distinct_id: Callable[[], str],
+    ) -> None:
+        self._http = http_client
+        self._site_id = site_id
+        self._get_distinct_id = get_distinct_id
+
+    def _base(self) -> Dict[str, Any]:
+        return {"siteId": self._site_id, "userId": self._get_distinct_id()}
+
+    def set_group(
+        self, group_key: str, group_id: Union[str, List[str]]
+    ) -> ApiResult:
+        return self._http.post_group(  # type: ignore[attr-defined]
+            endpoints.GROUPS_SET,
+            {**self._base(), "groupKey": group_key, "groupId": group_id},
+        )
+
+    def add_group(self, group_key: str, group_id: str) -> ApiResult:
+        return self._http.post_group(  # type: ignore[attr-defined]
+            endpoints.GROUPS_ADD,
+            {**self._base(), "groupKey": group_key, "groupId": group_id},
+        )
+
+    def remove_group(self, group_key: str, group_id: str) -> ApiResult:
+        return self._http.post_group(  # type: ignore[attr-defined]
+            endpoints.GROUPS_REMOVE,
+            {**self._base(), "groupKey": group_key, "groupId": group_id},
+        )
+
+    def get_group(self, group_key: str, group_id: str) -> GroupProfile:
+        return GroupProfile(
+            self._http,
+            self._site_id,
+            self._get_distinct_id(),
+            group_key,
+            group_id,
+        )

trodo/managers/people_manager.py

@@ -0,0 +1,77 @@
+"""People (user profile) methods."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from ..api import endpoints
+from ..types import ApiResult
+
+
+class PeopleManager:
+    def __init__(
+        self,
+        http_client: object,
+        site_id: str,
+        get_distinct_id: Callable[[], str],
+    ) -> None:
+        self._http = http_client
+        self._site_id = site_id
+        self._get_distinct_id = get_distinct_id
+
+    def _base(self) -> Dict[str, Any]:
+        return {"siteId": self._site_id, "userId": self._get_distinct_id()}
+
+    def set(self, properties: Dict[str, Any]) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_SET, {**self._base(), "properties": properties}
+        )
+
+    def set_once(self, properties: Dict[str, Any]) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_SET_ONCE, {**self._base(), "properties": properties}
+        )
+
+    def unset(self, keys: Union[str, List[str]]) -> ApiResult:
+        k = [keys] if isinstance(keys, str) else keys
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_UNSET, {**self._base(), "keys": k}
+        )
+
+    def increment(self, key: str, amount: float = 1) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_INCREMENT, {**self._base(), "key": key, "amount": amount}
+        )
+
+    def append(self, key: str, values: List[Any]) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_APPEND, {**self._base(), "key": key, "values": values}
+        )
+
+    def union(self, key: str, values: List[Any]) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_UNION, {**self._base(), "key": key, "values": values}
+        )
+
+    def remove(self, key: str, values: List[Any]) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_REMOVE, {**self._base(), "key": key, "values": values}
+        )
+
+    def track_charge(
+        self, amount: float, properties: Optional[Dict[str, Any]] = None
+    ) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_TRACK_CHARGE,
+            {**self._base(), "amount": amount, "properties": properties or {}},
+        )
+
+    def clear_charges(self) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_CLEAR_CHARGES, self._base()
+        )
+
+    def delete_user(self) -> ApiResult:
+        return self._http.post_people(  # type: ignore[attr-defined]
+            endpoints.PEOPLE_DELETE_USER, self._base()
+        )

trodo/queue/batch_flusher.py

@@ -0,0 +1,52 @@
+"""Background timer-based batch flusher."""
+
+from __future__ import annotations
+
+import threading
+from typing import Optional
+
+from .event_queue import EventQueue
+
+
+class BatchFlusher:
+    def __init__(
+        self,
+        queue: EventQueue,
+        http_client: object,
+        flush_interval: float,
+    ) -> None:
+        self._queue = queue
+        self._http = http_client
+        self._flush_interval = flush_interval
+        self._timer: Optional[threading.Timer] = None
+        self._lock = threading.Lock()
+
+    def start(self) -> None:
+        self._reschedule()
+
+    def stop(self) -> None:
+        with self._lock:
+            if self._timer:
+                self._timer.cancel()
+                self._timer = None
+
+    def flush(self) -> None:
+        events = self._queue.drain()
+        if not events:
+            return
+        self._http.post_bulk_events(events)  # type: ignore[attr-defined]
+
+    def _reschedule(self) -> None:
+        with self._lock:
+            if self._timer:
+                self._timer.cancel()
+            t = threading.Timer(self._flush_interval, self._tick)
+            t.daemon = True
+            t.start()
+            self._timer = t
+
+    def _tick(self) -> None:
+        try:
+            self.flush()
+        finally:
+            self._reschedule()

trodo/queue/event_queue.py

@@ -0,0 +1,32 @@
+"""Thread-safe in-memory event queue."""
+
+from __future__ import annotations
+
+import threading
+from typing import List
+
+from ..types import EventPayload
+
+
+class EventQueue:
+    def __init__(self, max_size: int = 500) -> None:
+        self._max_size = max_size
+        self._queue: List[EventPayload] = []
+        self._lock = threading.Lock()
+
+    def enqueue(self, event: EventPayload) -> bool:
+        """Returns True if flush threshold reached."""
+        with self._lock:
+            self._queue.append(event)
+            return len(self._queue) >= self._max_size
+
+    def drain(self) -> List[EventPayload]:
+        """Atomically take all queued events."""
+        with self._lock:
+            events = list(self._queue)
+            self._queue.clear()
+            return events
+
+    def size(self) -> int:
+        with self._lock:
+            return len(self._queue)

trodo/session/server_session.py

@@ -0,0 +1,74 @@
+"""Server session creation utilities."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from ..types import ServerSession
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def create_server_session(
+    site_id: str,
+    distinct_id: str,
+    session_id: Optional[str] = None,
+) -> ServerSession:
+    return ServerSession(
+        session_id=session_id or str(uuid.uuid4()),
+        site_id=site_id,
+        distinct_id=distinct_id,
+        start_time=now_iso(),
+        last_activity=time.time(),
+        confirmed=False,
+    )
+
+
+def build_session_payload(session: ServerSession) -> Dict[str, Any]:
+    return {
+        "session_id": session.session_id,
+        "site_id": session.site_id,
+        "user_id": session.distinct_id,
+        "distinct_id": session.distinct_id,
+        "team_id": None,
+        "start_time": session.start_time,
+        "end_time": None,
+        "last_activity": int(session.last_activity * 1000),
+        "duration": 0,
+        "pages_viewed": 0,
+        "is_bounce": False,
+        "previous_session_id": None,
+        "time_since_last_session": None,
+        "entry_page": None,
+        "exit_page": None,
+        "referrer": "server",
+        "ip_address": None,
+        "city": None,
+        "region": None,
+        "country": None,
+        "browser_name": None,
+        "browser_version": None,
+        "device_type": "server",
+        "os": None,
+        "resolution": None,
+        "user_agent": None,
+        "language": None,
+        "wallet_address": None,
+        "wallet_type": None,
+        "chain_name": None,
+        "is_web3_user": False,
+        "wallet_connected": False,
+        "utm_source": None,
+        "utm_medium": None,
+        "utm_campaign": None,
+        "utm_term": None,
+        "utm_content": None,
+        "utm_id": None,
+        "visited_pages": [],
+        "active_time_ms": 0,
+    }

trodo/session/session_manager.py

@@ -0,0 +1,74 @@
+"""Thread-safe in-process session cache."""
+
+from __future__ import annotations
+
+import threading
+from typing import Dict, Optional
+
+from ..types import ServerSession
+from .server_session import build_session_payload, create_server_session
+
+
+class SessionManager:
+    def __init__(self) -> None:
+        self._sessions: Dict[str, ServerSession] = {}
+        self._lock = threading.Lock()
+        self._confirmation_locks: Dict[str, threading.Event] = {}
+        self._confirmation_started: Dict[str, bool] = {}
+
+    def get_or_create(
+        self,
+        distinct_id: str,
+        site_id: str,
+        session_id: Optional[str] = None,
+    ) -> ServerSession:
+        with self._lock:
+            if distinct_id in self._sessions:
+                return self._sessions[distinct_id]
+            session = create_server_session(site_id, distinct_id, session_id)
+            self._sessions[distinct_id] = session
+            return session
+
+    def ensure_confirmed(self, session: ServerSession, http_client: object) -> None:
+        """
+        Block until the session has been confirmed via POST /api/sdk/track.
+        Idempotent — concurrent callers share a single confirmation attempt.
+        """
+        if session.confirmed:
+            return
+
+        key = session.distinct_id
+
+        with self._lock:
+            if session.confirmed:
+                return
+            # Check if confirmation already in-flight
+            if key not in self._confirmation_locks:
+                event = threading.Event()
+                self._confirmation_locks[key] = event
+                should_run = True
+            else:
+                event = self._confirmation_locks[key]
+                should_run = False
+
+        if should_run:
+            try:
+                payload = build_session_payload(session)
+                http_client.post_track(payload)  # type: ignore[attr-defined]
+            except Exception:
+                pass  # Confirmation failure is non-fatal
+            finally:
+                session.confirmed = True
+                with self._lock:
+                    self._confirmation_locks.pop(key, None)
+                event.set()
+        else:
+            event.wait(timeout=10)
+
+    def invalidate(self, distinct_id: str) -> None:
+        with self._lock:
+            self._sessions.pop(distinct_id, None)
+            self._confirmation_locks.pop(distinct_id, None)
+
+    def get_global_session(self, site_id: str) -> ServerSession:
+        return self.get_or_create("server_global", site_id)

trodo/types.py

@@ -0,0 +1,79 @@
+"""Type definitions for the Trodo Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+# ----------------------------------------------------------------------------
+# Configuration
+# ----------------------------------------------------------------------------
+
+@dataclass
+class TrodoConfig:
+    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  # Callable[[Exception], None]
+    debug: bool = False
+
+
+# ----------------------------------------------------------------------------
+# Session
+# ----------------------------------------------------------------------------
+
+@dataclass
+class ServerSession:
+    session_id: str
+    site_id: str
+    distinct_id: str
+    start_time: str      # ISO 8601
+    last_activity: float  # epoch seconds
+    confirmed: bool = False
+
+
+# ----------------------------------------------------------------------------
+# Events
+# ----------------------------------------------------------------------------
+
+@dataclass
+class EventPayload:
+    event_type: str      # 'custom' | 'auto'
+    event_name: str
+    event_category: str
+    session_id: str
+    user_id: str
+    custom_properties: Dict[str, Any] = field(default_factory=dict)
+    page_data: None = None
+    auto_event_data: Optional[Dict[str, Any]] = None
+    element_data: None = None
+    override_data: None = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "event_type": self.event_type,
+            "event_name": self.event_name,
+            "event_category": self.event_category,
+            "session_id": self.session_id,
+            "user_id": self.user_id,
+            "custom_properties": self.custom_properties,
+            "page_data": self.page_data,
+            "auto_event_data": self.auto_event_data,
+            "element_data": self.element_data,
+            "override_data": self.override_data,
+        }
+
+
+# ----------------------------------------------------------------------------
+# Results
+# ----------------------------------------------------------------------------
+
+ApiResult = Dict[str, Any]
+IdentifyResult = Dict[str, Any]
+WalletAddressResult = Dict[str, Any]
+ResetResult = Dict[str, Any]