trodo-python 1.0.0__py3-none-any.whl

trodo/user_context.py

@@ -0,0 +1,224 @@
+"""UserContext — user-bound proxy for all Trodo SDK operations."""
+
+from __future__ import annotations
+
+import traceback
+from typing import Any, Dict, List, Optional, Union, TYPE_CHECKING
+
+from .managers.people_manager import PeopleManager
+from .managers.group_manager import GroupManager, GroupProfile
+from .types import (
+    ApiResult,
+    IdentifyResult,
+    ResetResult,
+    WalletAddressResult,
+    EventPayload,
+)
+from .session.server_session import now_iso
+
+if TYPE_CHECKING:
+    from .api.http_client import HttpClient
+    from .session.session_manager import SessionManager
+    from .queue.event_queue import EventQueue
+    from .queue.batch_flusher import BatchFlusher
+    from .auto.auto_event_manager import AutoEventManager
+    from .types import ServerSession
+
+
+class UserContext:
+    def __init__(
+        self,
+        distinct_id: str,
+        site_id: str,
+        http_client: "HttpClient",
+        session_manager: "SessionManager",
+        event_queue: Optional["EventQueue"],
+        batch_flusher: Optional["BatchFlusher"],
+        auto_event_manager: "AutoEventManager",
+        session_id: Optional[str] = None,
+    ) -> None:
+        self._distinct_id = distinct_id
+        self._site_id = site_id
+        self._http = http_client
+        self._session_manager = session_manager
+        self._event_queue = event_queue
+        self._batch_flusher = batch_flusher
+        self._auto_event_manager = auto_event_manager
+        self._session_id_override = session_id
+        self._session: Optional["ServerSession"] = None
+
+        # Eagerly initialise session
+        self._session = self._session_manager.get_or_create(
+            distinct_id, site_id, session_id
+        )
+
+        self.people = PeopleManager(
+            http_client, site_id, lambda: self._get_distinct_id()
+        )
+        self._group_manager = GroupManager(
+            http_client, site_id, lambda: self._get_distinct_id()
+        )
+
+    def _get_distinct_id(self) -> str:
+        if self._session:
+            return self._session.distinct_id
+        return self._distinct_id
+
+    def _get_session(self) -> "ServerSession":
+        if not self._session:
+            self._session = self._session_manager.get_or_create(
+                self._distinct_id, self._site_id, self._session_id_override
+            )
+        return self._session
+
+    def _send_event(
+        self,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        category: str = "custom",
+    ) -> None:
+        session = self._get_session()
+        self._session_manager.ensure_confirmed(session, self._http)
+
+        event = EventPayload(
+            event_type="custom",
+            event_name=event_name,
+            event_category=category,
+            session_id=session.session_id,
+            user_id=session.distinct_id,
+            custom_properties=properties or {},
+        )
+
+        if self._event_queue and self._batch_flusher:
+            should_flush = self._event_queue.enqueue(event)
+            if should_flush:
+                self._batch_flusher.flush()
+        else:
+            self._http.post_event(event)
+
+    # --------------------------------------------------------------------------
+    # Event Tracking
+    # --------------------------------------------------------------------------
+
+    def track(
+        self,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        category: str = "custom",
+    ) -> None:
+        self._send_event(event_name, properties, category)
+
+    def track_event(
+        self,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        category: str = "custom",
+    ) -> None:
+        """Alias for track() — matches frontend SDK naming."""
+        self._send_event(event_name, properties, category)
+
+    # --------------------------------------------------------------------------
+    # Identity
+    # --------------------------------------------------------------------------
+
+    def identify(self, identify_id: str) -> IdentifyResult:
+        session = self._get_session()
+        self._session_manager.ensure_confirmed(session, self._http)
+
+        result = self._http.post_identify({
+            "siteId": self._site_id,
+            "sessionId": session.session_id,
+            "userId": session.distinct_id,
+            "distinctId": session.distinct_id,
+            "identifyId": identify_id,
+        })
+
+        new_distinct_id = result.get("newDistinctId") or result.get("distinctId")
+        if new_distinct_id and new_distinct_id != session.distinct_id:
+            session.distinct_id = new_distinct_id
+
+        return result
+
+    def wallet_address(self, wallet_addr: str) -> WalletAddressResult:
+        session = self._get_session()
+        self._session_manager.ensure_confirmed(session, self._http)
+
+        return self._http.post_wallet_address({
+            "siteId": self._site_id,
+            "sessionId": session.session_id,
+            "userId": session.distinct_id,
+            "distinctId": session.distinct_id,
+            "walletAddress": wallet_addr,
+        })
+
+    def reset(self) -> ResetResult:
+        session = self._get_session()
+        result = self._http.post_reset({
+            "siteId": self._site_id,
+            "sessionId": session.session_id,
+            "userId": session.distinct_id,
+            "distinctId": session.distinct_id,
+        })
+        self._session_manager.invalidate(self._distinct_id)
+        self._session = None
+        return result
+
+    # --------------------------------------------------------------------------
+    # People — accessible via user.people.set(...) etc.
+    # --------------------------------------------------------------------------
+
+    # --------------------------------------------------------------------------
+    # Groups
+    # --------------------------------------------------------------------------
+
+    def set_group(self, group_key: str, group_id: Union[str, List[str]]) -> ApiResult:
+        self._get_session()
+        return self._group_manager.set_group(group_key, group_id)
+
+    def add_group(self, group_key: str, group_id: str) -> ApiResult:
+        self._get_session()
+        return self._group_manager.add_group(group_key, group_id)
+
+    def remove_group(self, group_key: str, group_id: str) -> ApiResult:
+        self._get_session()
+        return self._group_manager.remove_group(group_key, group_id)
+
+    def get_group(self, group_key: str, group_id: str) -> GroupProfile:
+        return self._group_manager.get_group(group_key, group_id)
+
+    # --------------------------------------------------------------------------
+    # Error capture
+    # --------------------------------------------------------------------------
+
+    def capture_error(
+        self,
+        error: Exception,
+        severity: str = "error",
+    ) -> None:
+        session = self._get_session()
+        self._auto_event_manager.track_error(
+            error,
+            error_type=type(error).__name__,
+            severity=severity,
+            distinct_id=session.distinct_id,
+        )
+
+    # --------------------------------------------------------------------------
+    # Auto events (per-context toggle)
+    # --------------------------------------------------------------------------
+
+    def enable_auto_events(self) -> None:
+        self._auto_event_manager.enable()
+
+    def disable_auto_events(self) -> None:
+        self._auto_event_manager.disable()
+
+    # --------------------------------------------------------------------------
+    # Session info
+    # --------------------------------------------------------------------------
+
+    def get_session_id(self) -> Optional[str]:
+        return self._session.session_id if self._session else None
+
+    def get_current_distinct_id(self) -> str:
+        return self._get_distinct_id()

trodo_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: trodo-python
+Version: 1.0.0
+Summary: Trodo Analytics SDK for Python — server-side event tracking
+License: ISC
+Keywords: analytics,tracking,trodo,server-side
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.27.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# trodo-python
+
+Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, and manage people/groups — all merging seamlessly with your frontend Trodo data under the same `site_id`.
+
+## Installation
+
+```bash
+pip install trodo-python
+```
+
+For async support (optional):
+
+```bash
+pip install trodo-python[async]
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+import trodo
+
+# Initialize once at app startup
+trodo.init(
+    site_id='your-site-id',
+    debug=False,        # optional: log API calls
+    auto_events=True,   # optional: hook sys.excepthook
+)
+
+# Get a user context
+user = trodo.for_user('user-123')
+
+# Track a custom event
+user.track('purchase_completed', {'amount': 99.99, 'plan': 'pro'})
+
+# Identify the user (merges with frontend events under the same identity)
+user.identify('user@example.com')   # distinct_id becomes id_user@example.com
+
+# Update people profile
+user.people.set({'plan': 'pro', 'company': 'Acme'})
+
+# Track a server-side error
+user.capture_error(Exception('payment failed'))
+
+# Flush queued events before process exit
+trodo.shutdown()
+```
+
+## Flask / FastAPI Example
+
+```python
+# Flask
+from flask import Flask, request
+import trodo
+
+app = Flask(__name__)
+trodo.init(site_id='your-site-id')
+
+@app.route('/purchase', methods=['POST'])
+def purchase():
+    user_id = request.json['user_id']
+    user = trodo.for_user(user_id)
+    user.track('purchase_completed', {'amount': request.json['amount']})
+    return {'ok': True}
+```
+
+## Cross-SDK Identity Merging
+
+Frontend and backend events merge when both sides call `identify()` with the same value:
+
+```python
+# Python SDK
+user.identify('user@example.com')    # → id_user@example.com
+
+# Browser SDK (same value)
+# Trodo.identify('user@example.com') → id_user@example.com
+
+# Both event streams now appear together in the Trodo dashboard
+```
+
+## API Reference
+
+### `trodo.init(config)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `site_id` | `str` | required | Your Trodo site ID |
+| `api_base` | `str` | `https://sdkapi.trodo.ai` | API base URL |
+| `debug` | `bool` | `False` | Log API requests/responses |
+| `auto_events` | `bool` | `False` | Hook `sys.excepthook` + `threading.excepthook` |
+| `retries` | `int` | `3` | HTTP retry attempts on 5xx errors |
+| `timeout` | `int` | `10` | HTTP timeout in seconds |
+| `batch_enabled` | `bool` | `False` | Queue events and flush in bulk |
+| `batch_size` | `int` | `50` | Max events per batch flush |
+| `batch_flush_interval` | `float` | `5.0` | Flush interval in seconds |
+| `on_error` | `callable` | `None` | Callback for SDK errors |
+
+### `trodo.for_user(distinct_id, session_id=None)`
+
+Returns a user-bound context. All subsequent calls use this user's session.
+
+```python
+user = trodo.for_user(
+    'user-123',
+    session_id=request.cookies.get('trodo_session'),  # optional: correlate with browser session
+)
+```
+
+### User Context Methods
+
+```python
+user.track(event_name, properties=None)          # Track custom event
+user.track_event(event_name, properties=None)    # Alias for track()
+user.identify(identify_id)                       # Merge identity
+user.wallet_address(address)                     # Set crypto wallet address
+user.reset()                                     # Clear session context
+user.capture_error(exception)                    # Track server_error event
+
+# People profile
+user.people.set(properties)
+user.people.set_once(properties)
+user.people.unset(keys)
+user.people.increment(properties)
+user.people.append(properties)
+user.people.union(properties)
+user.people.remove(properties)
+user.people.track_charge(amount, properties=None)
+user.people.clear_charges()
+user.people.delete_user()
+
+# Groups
+user.set_group(group_key, group_id)
+user.add_group(group_key, group_id)
+user.remove_group(group_key, group_id)
+group = user.get_group(group_key, group_id)
+group.set(properties)
+group.set_once(properties)
+group.union(properties)
+group.remove(properties)
+group.unset(keys)
+group.increment(properties)
+group.append(properties)
+group.delete()
+```
+
+### Direct Call Pattern (for pipelines/scripts)
+
+```python
+trodo.track('user-123', 'event_name', {'key': 'value'})
+trodo.identify('user-123', 'identify_id')
+trodo.people_set('user-123', {'plan': 'pro'})
+trodo.set_group('user-123', 'company', 'acme')
+```
+
+### Global Methods
+
+```python
+trodo.enable_auto_events()    # Enable sys.excepthook hooks
+trodo.disable_auto_events()   # Disable hooks
+trodo.flush()                 # Flush pending batch queue
+trodo.shutdown()              # Flush + stop background timers
+```
+
+## Auto Events
+
+When `auto_events=True`, the SDK wraps Python's exception hooks and sends `server_error` events to Trodo:
+
+- `sys.excepthook` — unhandled exceptions in the main thread
+- `threading.excepthook` — unhandled exceptions in threads
+
+These events use `distinct_id: 'server_global'` in the dashboard.
+
+Per-user error capture: `user.capture_error(e)` uses the user's own `distinct_id`.
+
+## Batching
+
+```python
+trodo.init(
+    site_id='your-site-id',
+    batch_enabled=True,
+    batch_size=100,
+    batch_flush_interval=3.0,
+)
+
+# Events are queued and flushed every 3s or when 100 events accumulate
+user.track('page_view')
+
+# Always flush before process exit
+import atexit
+atexit.register(trodo.shutdown)
+```
+
+## Thread Safety
+
+The SDK is thread-safe. `SessionManager`, `EventQueue`, and `BatchFlusher` all use `threading.Lock` internally. Safe to use in multi-threaded Flask/Django/FastAPI applications.
+
+## License
+
+ISC

trodo_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+trodo/__init__.py,sha256=YF8iWrzi3W3I44Q6eQ5GVSZLwJAKifiDsRuM5jbUp4s,3633
+trodo/client.py,sha256=YjLAb-CAs-lYJ_JdD1WdjvByWheDMonUrr6Z5wL1SJc,7251
+trodo/types.py,sha256=OOVdmihZMu9f2zxcSJKzUWXc4-a7gKT4txBUn0K9CGo,2517
+trodo/user_context.py,sha256=K_6Wwb3J9jyKfV60fZKhAUd6HS_Ia-pb92eSVtNjGeY,8083
+trodo/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/api/async_client.py,sha256=-DEB0ZGtsf3eybe6MDA9RyNd2A1J1sNswDWj9GeyCdw,3504
+trodo/api/endpoints.py,sha256=SrAQfPfm3dq4W8it3g0GYiHUcESwpmpp-sH0R7SQe7I,818
+trodo/api/http_client.py,sha256=0Ij51cHAVMc708ai0MlKJl5VFqnBIJ3EdbsNMogYg68,3206
+trodo/auto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/auto/auto_event_manager.py,sha256=uuSUPMfix7Mw9Tqmdgk682tGSmYwlEptmm0yk6BGyi0,4381
+trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/managers/group_manager.py,sha256=dQGVLFkQVYieFRIU91g8ew93D2eVNMLu4tFn867_6cA,3648
+trodo/managers/people_manager.py,sha256=EsjruZRd-l9zOZylU0m9PPbaPlofkMk2hYaRKjLwElA,2959
+trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/queue/batch_flusher.py,sha256=cTVhVtiil2G_V9-eF9kHuYw7rrjkCwDOhecTFCHTfSQ,1350
+trodo/queue/event_queue.py,sha256=MOf993yFfOAEUKZ2l294T9_mxRMLvu4cd9PBb6jl-J8,904
+trodo/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/session/server_session.py,sha256=CE9bxJ6vCoqMs23BQpb8Kaw1K0f4eoa2L4aeuoozvpU,2044
+trodo/session/session_manager.py,sha256=JV1sZfCdA8BaGw30-DZyTJtMj93FFzGiuhInkboTCh8,2599
+trodo_python-1.0.0.dist-info/METADATA,sha256=qtLcOqaQkHXPjHWUs2wUU5QtCypoJLKClM9xdUgWWQo,6847
+trodo_python-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trodo_python-1.0.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-1.0.0.dist-info/RECORD,,

trodo_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trodo_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trodo