truesight-sdk 0.1.0a1__tar.gz

truesight_sdk-0.1.0a1/.gitignore

@@ -0,0 +1,66 @@
+# Rust
+/target/
+**/*.rs.bk
+*.pdb
+
+# Node
+node_modules/
+dist/
+build/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Gradle / KMM
+.gradle/
+sdks/kmm/build/
+sdks/kmm/**/build/
+sdks/kmm/local.properties
+sdks/kmm/.kotlin/
+**/*.klib
+
+# Python SDK
+sdks/python/.venv/
+sdks/python/dist/
+sdks/python/build/
+**/*.egg-info/
+sdks/python/.pytest_cache/
+sdks/python/.mypy_cache/
+sdks/python/.ruff_cache/
+**/__pycache__/
+
+# Database
+*.db
+*.sqlite
+
+# Logs
+*.log
+
+# Docker volumes
+clickhouse_data/
+postgres_data/
+
+# Lock files (pnpm is canonical, npm lock is SDK-local)
+# sdks/web/package-lock.json is committed for npm publish
+
+# Superpowers brainstorm artifacts
+.superpowers/
+
+# Claude Code
+.claude/
+.gstack/

truesight_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: truesight-sdk
+Version: 0.1.0a1
+Summary: Server-side Python SDK for TrueSight analytics ingestion
+Project-URL: Homepage, https://github.com/komorebitech/cf-truesight
+Project-URL: Source, https://github.com/komorebitech/cf-truesight/tree/master/sdks/python
+Project-URL: Issues, https://github.com/komorebitech/cf-truesight/issues
+Author-email: Cityflo Engineering <tech@cityflo.com>
+License-Expression: MIT
+Keywords: analytics,cityflo,event-tracking,truesight
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Requires-Dist: urllib3>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# truesight-sdk
+
+Server-side Python SDK for [TrueSight](https://github.com/komorebitech/cf-truesight) analytics ingestion.
+
+Designed for backends that emit events on behalf of authenticated users (Django, Flask, FastAPI, Airflow DAGs, management commands). Sync by design — if you need async, wrap calls in your own task queue.
+
+## Installation
+
+```bash
+pip install truesight-sdk
+```
+
+Python 3.10+.
+
+## Quick Start
+
+### Single event
+
+```python
+from truesight_sdk import TrueSightClient
+
+client = TrueSightClient(
+    api_key="ts_server_live_...",
+    base_url="https://ingest.truesight.example.com",
+)
+
+client.track(
+    event_name="Purchased Lite Pack",
+    user_id=str(customer.pk),
+    properties={"plan_slug": "5-30-days", "amount": 1200},
+)
+```
+
+### User profile update (identify)
+
+```python
+client.identify(
+    user_id=str(customer.pk),
+    email=customer.email,
+    properties={
+        "home_locality": "Andheri",
+        "favourite_route": "M1",
+        "weekly_subscription_active": True,
+    },
+)
+```
+
+This upserts the user's row in `truesight.user_profiles` (latest-write-wins merge of the `properties` blob) and also appends a `$identify` event to the stream for history.
+
+### Batched ingestion (Airflow / cron / bulk syncs)
+
+For workloads that emit many events in a tight loop, use `BatchingClient` to amortize HTTP overhead:
+
+```python
+from truesight_sdk import BatchingClient, TrueSightClient
+
+inner = TrueSightClient(api_key="ts_server_live_...", base_url="...")
+
+with BatchingClient(inner, batch_size=100, flush_interval_seconds=5.0) as batcher:
+    for customer in qs.iterator():
+        batcher.identify(
+            user_id=str(customer.pk),
+            properties=build_profile(customer),
+        )
+# Buffers drain on context exit.
+```
+
+`BatchingClient` is thread-safe; multiple producer threads can call `track()` / `identify()` concurrently.
+
+### Reading events (admin queries)
+
+The SDK also wraps TrueSight's admin event-query endpoint for read-path consumers:
+
+```python
+from truesight_sdk import AdminQueryClient
+
+reader = AdminQueryClient(admin_token="...", base_url="https://admin.truesight.example.com")
+
+page = reader.fetch_events(
+    project_id="b219fb11-9a63-4843-8126-a3dc05b330a5",
+    event_name="Purchased Lite Pack",
+    from_=datetime(2026, 5, 1, tzinfo=timezone.utc),
+    to=datetime(2026, 5, 28, tzinfo=timezone.utc),
+    limit=500,
+)
+```
+
+## API Keys
+
+Server keys are scoped — they can only call `/v1/server/*` endpoints. Issue one via the CLI:
+
+```bash
+truesight projects api-keys create --scope server --label "<your service>"
+```
+
+The plaintext key is returned **once** at creation time. Store it in your secrets manager.
+
+## Error Handling
+
+All errors subclass `TrueSightError`:
+
+```python
+from truesight_sdk import (
+    AuthError,        # 401 — bad / revoked key
+    Forbidden,        # 403 — wrong scope for this endpoint
+    ValidationError,  # 400/422 — payload rejected
+    RateLimited,      # 429 — slow down (after SDK's own retry budget)
+    ServerError,      # 5xx — TrueSight is degraded (after retries)
+    TrueSightError,   # base class — catch this to handle any SDK error
+)
+
+try:
+    client.track("x", user_id="42")
+except RateLimited:
+    schedule_retry(...)
+except TrueSightError as exc:
+    log.exception("truesight ingest failed", request_id=exc.request_id)
+```
+
+Every error carries `status_code`, `request_id` (when the server returned one), and `response_body` for log correlation.
+
+## Retry Idempotency
+
+The SDK auto-generates a fresh `event_id` (UUIDv4) for every event when one isn't supplied. If you need retry idempotency (e.g. inside a Celery task that may run twice), pass an explicit `event_id` stable across retries:
+
+```python
+from truesight_sdk import TrackEvent
+from uuid import uuid5, NAMESPACE_URL
+
+stable_id = uuid5(NAMESPACE_URL, f"booking-confirmed:{booking.pk}")
+client.track_batch([
+    TrackEvent(
+        event_name="Booking Confirmed",
+        user_id=str(booking.customer_id),
+        event_id=stable_id,
+        properties={"booking_id": booking.pk},
+    ),
+])
+```
+
+The server dedups on `(project_id, event_id)` via ClickHouse's `ReplacingMergeTree`, so retries with the same id collapse to a single row.
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run unit tests (no network)
+pytest
+
+# Run integration tests against a local TrueSight stack
+export TRUESIGHT_BASE_URL=http://localhost:8080
+export TRUESIGHT_API_KEY=ts_server_test_...
+pytest -m integration
+
+# Lint + typecheck
+ruff check src/ tests/
+mypy src/
+```
+
+## Versioning
+
+Semver. `0.x` is alpha — the public API may shift; pin the patch version until `1.0`.
+
+## License
+
+MIT — see top-level repo.

truesight_sdk-0.1.0a1/README.md

@@ -0,0 +1,168 @@
+# truesight-sdk
+
+Server-side Python SDK for [TrueSight](https://github.com/komorebitech/cf-truesight) analytics ingestion.
+
+Designed for backends that emit events on behalf of authenticated users (Django, Flask, FastAPI, Airflow DAGs, management commands). Sync by design — if you need async, wrap calls in your own task queue.
+
+## Installation
+
+```bash
+pip install truesight-sdk
+```
+
+Python 3.10+.
+
+## Quick Start
+
+### Single event
+
+```python
+from truesight_sdk import TrueSightClient
+
+client = TrueSightClient(
+    api_key="ts_server_live_...",
+    base_url="https://ingest.truesight.example.com",
+)
+
+client.track(
+    event_name="Purchased Lite Pack",
+    user_id=str(customer.pk),
+    properties={"plan_slug": "5-30-days", "amount": 1200},
+)
+```
+
+### User profile update (identify)
+
+```python
+client.identify(
+    user_id=str(customer.pk),
+    email=customer.email,
+    properties={
+        "home_locality": "Andheri",
+        "favourite_route": "M1",
+        "weekly_subscription_active": True,
+    },
+)
+```
+
+This upserts the user's row in `truesight.user_profiles` (latest-write-wins merge of the `properties` blob) and also appends a `$identify` event to the stream for history.
+
+### Batched ingestion (Airflow / cron / bulk syncs)
+
+For workloads that emit many events in a tight loop, use `BatchingClient` to amortize HTTP overhead:
+
+```python
+from truesight_sdk import BatchingClient, TrueSightClient
+
+inner = TrueSightClient(api_key="ts_server_live_...", base_url="...")
+
+with BatchingClient(inner, batch_size=100, flush_interval_seconds=5.0) as batcher:
+    for customer in qs.iterator():
+        batcher.identify(
+            user_id=str(customer.pk),
+            properties=build_profile(customer),
+        )
+# Buffers drain on context exit.
+```
+
+`BatchingClient` is thread-safe; multiple producer threads can call `track()` / `identify()` concurrently.
+
+### Reading events (admin queries)
+
+The SDK also wraps TrueSight's admin event-query endpoint for read-path consumers:
+
+```python
+from truesight_sdk import AdminQueryClient
+
+reader = AdminQueryClient(admin_token="...", base_url="https://admin.truesight.example.com")
+
+page = reader.fetch_events(
+    project_id="b219fb11-9a63-4843-8126-a3dc05b330a5",
+    event_name="Purchased Lite Pack",
+    from_=datetime(2026, 5, 1, tzinfo=timezone.utc),
+    to=datetime(2026, 5, 28, tzinfo=timezone.utc),
+    limit=500,
+)
+```
+
+## API Keys
+
+Server keys are scoped — they can only call `/v1/server/*` endpoints. Issue one via the CLI:
+
+```bash
+truesight projects api-keys create --scope server --label "<your service>"
+```
+
+The plaintext key is returned **once** at creation time. Store it in your secrets manager.
+
+## Error Handling
+
+All errors subclass `TrueSightError`:
+
+```python
+from truesight_sdk import (
+    AuthError,        # 401 — bad / revoked key
+    Forbidden,        # 403 — wrong scope for this endpoint
+    ValidationError,  # 400/422 — payload rejected
+    RateLimited,      # 429 — slow down (after SDK's own retry budget)
+    ServerError,      # 5xx — TrueSight is degraded (after retries)
+    TrueSightError,   # base class — catch this to handle any SDK error
+)
+
+try:
+    client.track("x", user_id="42")
+except RateLimited:
+    schedule_retry(...)
+except TrueSightError as exc:
+    log.exception("truesight ingest failed", request_id=exc.request_id)
+```
+
+Every error carries `status_code`, `request_id` (when the server returned one), and `response_body` for log correlation.
+
+## Retry Idempotency
+
+The SDK auto-generates a fresh `event_id` (UUIDv4) for every event when one isn't supplied. If you need retry idempotency (e.g. inside a Celery task that may run twice), pass an explicit `event_id` stable across retries:
+
+```python
+from truesight_sdk import TrackEvent
+from uuid import uuid5, NAMESPACE_URL
+
+stable_id = uuid5(NAMESPACE_URL, f"booking-confirmed:{booking.pk}")
+client.track_batch([
+    TrackEvent(
+        event_name="Booking Confirmed",
+        user_id=str(booking.customer_id),
+        event_id=stable_id,
+        properties={"booking_id": booking.pk},
+    ),
+])
+```
+
+The server dedups on `(project_id, event_id)` via ClickHouse's `ReplacingMergeTree`, so retries with the same id collapse to a single row.
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run unit tests (no network)
+pytest
+
+# Run integration tests against a local TrueSight stack
+export TRUESIGHT_BASE_URL=http://localhost:8080
+export TRUESIGHT_API_KEY=ts_server_test_...
+pytest -m integration
+
+# Lint + typecheck
+ruff check src/ tests/
+mypy src/
+```
+
+## Versioning
+
+Semver. `0.x` is alpha — the public API may shift; pin the patch version until `1.0`.
+
+## License
+
+MIT — see top-level repo.

truesight_sdk-0.1.0a1/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truesight-sdk"
+description = "Server-side Python SDK for TrueSight analytics ingestion"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Cityflo Engineering", email = "tech@cityflo.com" },
+]
+keywords = ["analytics", "truesight", "event-tracking", "cityflo"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.28",
+    "urllib3>=2.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/komorebitech/cf-truesight"
+Source = "https://github.com/komorebitech/cf-truesight/tree/master/sdks/python"
+Issues = "https://github.com/komorebitech/cf-truesight/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "responses>=0.25",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "types-requests",
+]
+
+[tool.hatch.version]
+path = "src/truesight_sdk/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/truesight_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+disallow_untyped_decorators = false
+
+[[tool.mypy.overrides]]
+module = ["responses.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: integration test that requires a running TrueSight instance (skipped unless TRUESIGHT_BASE_URL is set)",
+]

truesight_sdk-0.1.0a1/src/truesight_sdk/__init__.py

@@ -0,0 +1,54 @@
+"""TrueSight Python SDK — server-side analytics ingestion.
+
+This SDK targets server-to-server use cases (Django/Flask/FastAPI backends,
+Airflow DAGs, management commands) that emit events on behalf of authenticated
+users. It is intentionally sync; if you need an async wrapper, wire it up via
+your own task queue (e.g. Celery).
+
+Quick start:
+
+    from truesight_sdk import TrueSightClient
+
+    client = TrueSightClient(
+        api_key="ts_server_live_...",
+        base_url="https://ingest.truesight.example.com",
+    )
+    client.track(
+        event_name="Purchased Lite Pack",
+        user_id=str(customer.pk),
+        properties={"plan_slug": "5-30-days", "amount": 1200},
+    )
+
+For bulk-sync workloads (Airflow DAGs, nightly profile syncs), use
+``BatchingClient`` to amortize HTTP overhead across many events.
+"""
+
+from truesight_sdk._version import __version__
+from truesight_sdk.batching import BatchingClient
+from truesight_sdk.client import TrueSightClient
+from truesight_sdk.errors import (
+    AuthError,
+    Forbidden,
+    RateLimited,
+    ServerError,
+    TrueSightError,
+    ValidationError,
+)
+from truesight_sdk.models import EventType, IdentifyEvent, TrackEvent
+from truesight_sdk.query import AdminQueryClient
+
+__all__ = [
+    "AdminQueryClient",
+    "AuthError",
+    "BatchingClient",
+    "EventType",
+    "Forbidden",
+    "IdentifyEvent",
+    "RateLimited",
+    "ServerError",
+    "TrackEvent",
+    "TrueSightClient",
+    "TrueSightError",
+    "ValidationError",
+    "__version__",
+]

truesight_sdk-0.1.0a1/src/truesight_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a1"