qurvo-python 0.1.0__tar.gz

qurvo_python-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+node_modules/
+dist/
+dist-server/
+.turbo/
+*.tsbuildinfo
+.env
+.env.local
+.DS_Store
+.playwright-mcp/
+*.png
+
+# Kubernetes credentials
+*-config.yaml
+kubeconfig*
+config.yaml
+.idea
+values.local-secrets.yaml
+
+.last-deploy
+.claude/worktrees/*
+.claude/state/execution-state.json
+.claude/state/operations.log
+.claude/state/worktree-base-branch
+.claude/results/
+.claude/issues/
+.mcp.json
+
+apps/web/storybook-static/
+
+# Temporary Storybook stories (not committed)
+apps/web/src/**/*.tmp.stories.tsx

qurvo_python-0.1.0/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md -- qurvo-python
+
+Python SDK for Qurvo analytics. Mirrors the architecture of the TypeScript SDK (`@qurvo/sdk-core` + `@qurvo/sdk-node`).
+
+## Structure
+
+```
+packages/qurvo-python/
+├── pyproject.toml          # hatchling build, zero runtime deps, python>=3.9
+├── CLAUDE.md
+├── README.md               # User-facing docs with usage examples
+├── src/
+│   └── qurvo/
+│       ├── __init__.py     # Public API re-exports
+│       ├── _types.py       # Dataclasses (EventPayload, EventContext, etc.) + exceptions
+│       ├── _transport.py   # HttpTransport -- urllib + gzip, status code mapping
+│       ├── _queue.py       # EventQueue -- threaded batching, backoff, flush loop
+│       └── client.py       # Qurvo class -- public API, mirrors sdk-node/src/index.ts
+└── tests/
+    ├── conftest.py
+    ├── test_types.py
+    ├── test_transport.py
+    ├── test_queue.py
+    └── test_client.py
+```
+
+## Key Design Decisions
+
+- **Zero runtime dependencies** -- only stdlib (`urllib.request`, `gzip`, `json`, `dataclasses`, `threading`, `uuid`)
+- **`from __future__ import annotations`** everywhere for Python 3.9 compat with modern type hints
+- **Dataclasses with `asdict()` + None-filtering** for JSON serialization -- ingest expects absent fields, not null
+- **Private modules** (`_types.py`, `_transport.py`, `_queue.py`) -- public API via `__init__.py` re-exports
+- **`Qurvo` client class** (`client.py`) is the primary public interface -- mirrors `@qurvo/sdk-node`
+- **Status code mapping** mirrors TypeScript `FetchTransport`:
+  - 202 -> success
+  - 200 + `quota_limited` body -> `QuotaExceededError`
+  - 4xx -> `NonRetryableError` (SDK should drop, not retry)
+  - 5xx / network error -> generic exception (retryable)
+- **`$set` / `$set_once` envelope pattern** -- `user_properties: {"$set": {...}}` matches sdk-node behavior
+- **`sdk_name` / `sdk_version`** automatically added to `context` on every event
+- **`event_id`** via `uuid4()` for deduplication on retry
+
+## Commands
+
+```bash
+# Install in dev mode
+cd packages/qurvo-python && pip install -e ".[dev]"
+
+# Run tests
+cd packages/qurvo-python && pytest -v
+
+# Run tests with coverage
+cd packages/qurvo-python && pytest --cov=qurvo --cov-report=term-missing
+
+# Publish to PyPI
+cd packages/qurvo-python && python -m build && twine upload dist/*
+```
+
+## Related Packages
+
+- `@qurvo/sdk-core` -- TypeScript equivalent (types.ts, fetch-transport.ts, queue.ts)
+- `@qurvo/sdk-node` -- TypeScript Node.js client (index.ts -- direct API mirror)
+- `apps/ingest` -- Event ingestion endpoint (POST /v1/batch)

qurvo_python-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: qurvo-python
+Version: 0.1.0
+Summary: Qurvo analytics SDK for Python — zero-dependency event tracking
+License-Expression: MIT
+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.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qurvo-python
+
+Python SDK for [Qurvo](https://qurvo.pro) analytics. Zero runtime dependencies -- uses only the Python standard library.
+
+## Installation
+
+```bash
+pip install qurvo-python
+```
+
+## Quick Start
+
+```python
+from qurvo import Qurvo
+
+qurvo = Qurvo(api_key="qk_...")
+
+# Track a custom event
+qurvo.track("user-123", "purchase", {"amount": 99.99, "currency": "USD"})
+
+# Identify a user
+qurvo.identify("user-123", {"name": "John", "plan": "pro"})
+
+# Set user properties (overwrites existing)
+qurvo.set("user-123", {"plan": "enterprise"})
+
+# Set user properties only if not already set
+qurvo.set_once("user-123", {"first_seen": "2026-01-01"})
+
+# Track a screen view
+qurvo.screen("user-123", "HomeScreen", {"tab": "overview"})
+
+# Gracefully flush and shut down
+qurvo.shutdown()
+```
+
+## Configuration
+
+```python
+qurvo = Qurvo(
+    api_key="qk_...",                           # Required
+    endpoint="https://ingest.qurvo.pro",        # Default
+    flush_interval=5.0,                         # Seconds between flushes
+    flush_size=20,                              # Max events per batch
+    max_queue_size=1000,                        # Max queued events
+    timeout=30.0,                               # HTTP timeout in seconds
+    logger=lambda msg: print(f"[qurvo] {msg}"),  # Optional debug logger
+)
+```
+
+## API Reference
+
+### `Qurvo(api_key, **kwargs)`
+
+Create a new client instance. Starts a background thread that periodically flushes queued events to the ingest endpoint.
+
+### `.track(distinct_id, event, properties=None)`
+
+Track a custom event.
+
+### `.identify(distinct_id, user_properties, anonymous_id=None)`
+
+Identify a user and set their properties. Optionally merge an anonymous ID.
+
+### `.set(distinct_id, properties)`
+
+Set user properties (overwrites existing values). Uses the `$set` envelope pattern.
+
+### `.set_once(distinct_id, properties)`
+
+Set user properties only if they are not already set. Uses the `$set_once` envelope pattern.
+
+### `.screen(distinct_id, screen_name, properties=None)`
+
+Track a screen view event. The `screen_name` is added as `$screen_name` in properties.
+
+### `.shutdown(timeout=30.0)`
+
+Gracefully flush all remaining events and stop the background thread. Call this before your application exits.
+
+## Requirements
+
+- Python >= 3.9
+- No runtime dependencies
+
+## License
+
+MIT

qurvo_python-0.1.0/README.md

@@ -0,0 +1,88 @@
+# qurvo-python
+
+Python SDK for [Qurvo](https://qurvo.pro) analytics. Zero runtime dependencies -- uses only the Python standard library.
+
+## Installation
+
+```bash
+pip install qurvo-python
+```
+
+## Quick Start
+
+```python
+from qurvo import Qurvo
+
+qurvo = Qurvo(api_key="qk_...")
+
+# Track a custom event
+qurvo.track("user-123", "purchase", {"amount": 99.99, "currency": "USD"})
+
+# Identify a user
+qurvo.identify("user-123", {"name": "John", "plan": "pro"})
+
+# Set user properties (overwrites existing)
+qurvo.set("user-123", {"plan": "enterprise"})
+
+# Set user properties only if not already set
+qurvo.set_once("user-123", {"first_seen": "2026-01-01"})
+
+# Track a screen view
+qurvo.screen("user-123", "HomeScreen", {"tab": "overview"})
+
+# Gracefully flush and shut down
+qurvo.shutdown()
+```
+
+## Configuration
+
+```python
+qurvo = Qurvo(
+    api_key="qk_...",                           # Required
+    endpoint="https://ingest.qurvo.pro",        # Default
+    flush_interval=5.0,                         # Seconds between flushes
+    flush_size=20,                              # Max events per batch
+    max_queue_size=1000,                        # Max queued events
+    timeout=30.0,                               # HTTP timeout in seconds
+    logger=lambda msg: print(f"[qurvo] {msg}"),  # Optional debug logger
+)
+```
+
+## API Reference
+
+### `Qurvo(api_key, **kwargs)`
+
+Create a new client instance. Starts a background thread that periodically flushes queued events to the ingest endpoint.
+
+### `.track(distinct_id, event, properties=None)`
+
+Track a custom event.
+
+### `.identify(distinct_id, user_properties, anonymous_id=None)`
+
+Identify a user and set their properties. Optionally merge an anonymous ID.
+
+### `.set(distinct_id, properties)`
+
+Set user properties (overwrites existing values). Uses the `$set` envelope pattern.
+
+### `.set_once(distinct_id, properties)`
+
+Set user properties only if they are not already set. Uses the `$set_once` envelope pattern.
+
+### `.screen(distinct_id, screen_name, properties=None)`
+
+Track a screen view event. The `screen_name` is added as `$screen_name` in properties.
+
+### `.shutdown(timeout=30.0)`
+
+Gracefully flush all remaining events and stop the background thread. Call this before your application exits.
+
+## Requirements
+
+- Python >= 3.9
+- No runtime dependencies
+
+## License
+
+MIT

qurvo_python-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "qurvo-python"
+version = "0.1.0"
+description = "Qurvo analytics SDK for Python — zero-dependency event tracking"
+requires-python = ">=3.9"
+dependencies = []
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qurvo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qurvo_python-0.1.0/src/qurvo/__init__.py

@@ -0,0 +1,27 @@
+"""Qurvo analytics SDK for Python."""
+
+from __future__ import annotations
+
+from qurvo._types import (
+    BatchEnvelope,
+    EventContext,
+    EventPayload,
+    NonRetryableError,
+    QuotaExceededError,
+    SdkConfig,
+)
+from qurvo._transport import HttpTransport
+from qurvo._queue import EventQueue
+from qurvo.client import Qurvo
+
+__all__ = [
+    "BatchEnvelope",
+    "EventContext",
+    "EventPayload",
+    "EventQueue",
+    "HttpTransport",
+    "NonRetryableError",
+    "QuotaExceededError",
+    "Qurvo",
+    "SdkConfig",
+]

qurvo_python-0.1.0/src/qurvo/_queue.py

@@ -0,0 +1,263 @@
+"""Event queue with background flush thread, batching and exponential backoff.
+
+Mirrors ``@qurvo/sdk-core/src/queue.ts``.  Uses only stdlib
+(``threading``, ``collections.deque``) -- no third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import collections
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from qurvo._transport import HttpTransport
+from qurvo._types import (
+    LogFn,
+    NonRetryableError,
+    QuotaExceededError,
+)
+
+
+class EventQueue:
+    """Thread-safe event queue with automatic batched flushing.
+
+    Parameters
+    ----------
+    transport:
+        HTTP transport used to send batches.
+    endpoint:
+        Target URL (e.g. ``https://ingest.qurvo.io/v1/batch``).
+    api_key:
+        Project API key passed as ``x-api-key`` header.
+    flush_interval:
+        Seconds between automatic flushes (default 5.0).
+    flush_size:
+        Max events per batch (default 20).
+    max_queue_size:
+        When exceeded, oldest events are dropped (default 1000).
+    timeout:
+        HTTP timeout in seconds for each flush (default 30.0).
+    logger:
+        Optional logging callback.
+    """
+
+    def __init__(
+        self,
+        transport: HttpTransport,
+        endpoint: str,
+        api_key: str,
+        flush_interval: float = 5.0,
+        flush_size: int = 20,
+        max_queue_size: int = 1000,
+        timeout: float = 30.0,
+        logger: Optional[LogFn] = None,
+    ) -> None:
+        self._transport = transport
+        self._endpoint = endpoint
+        self._api_key = api_key
+        self._flush_interval = flush_interval
+        self._flush_size = flush_size
+        self._max_queue_size = max_queue_size
+        self._timeout = timeout
+        self._logger = logger
+
+        self._queue: collections.deque[Dict[str, Any]] = collections.deque()
+        self._lock = threading.Lock()
+        self._flushing = False
+        self._failure_count = 0
+        self._retry_after = 0.0
+        self._max_backoff = 30.0
+
+        self._stop_event = threading.Event()
+        self._flush_now_event = threading.Event()
+        self._timer_thread: Optional[threading.Thread] = None
+        self._stopped_permanently = False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def enqueue(self, payload: Dict[str, Any]) -> None:
+        """Add an event to the queue.
+
+        If the queue is at capacity, the oldest event is dropped.
+        If the queue reaches ``flush_size``, an immediate flush is triggered.
+        """
+        with self._lock:
+            if len(self._queue) >= self._max_queue_size:
+                self._queue.popleft()
+                if self._logger:
+                    self._logger(
+                        f"queue full ({self._max_queue_size}), oldest event dropped"
+                    )
+            self._queue.append(payload)
+            should_flush = len(self._queue) >= self._flush_size
+
+        if should_flush:
+            self._flush_now_event.set()
+            self.flush()
+
+    def start(self) -> None:
+        """Start the background flush timer thread."""
+        if self._timer_thread is not None and self._timer_thread.is_alive():
+            return
+        if self._stopped_permanently:
+            return
+        self._stop_event.clear()
+        self._timer_thread = threading.Thread(
+            target=self._flush_loop, daemon=True, name="qurvo-flush"
+        )
+        self._timer_thread.start()
+
+    def stop(self) -> None:
+        """Stop the background flush timer thread (does NOT flush remaining)."""
+        self._stop_event.set()
+        self._flush_now_event.set()  # wake up sleeping thread
+        if self._timer_thread is not None:
+            self._timer_thread.join(timeout=5.0)
+            self._timer_thread = None
+
+    def flush(self) -> None:
+        """Flush up to ``flush_size`` events synchronously.
+
+        Thread-safe: only one flush can run at a time (``_flushing`` guard).
+        The lock is held only for queue mutation, never during the HTTP call.
+        """
+        if self._flushing:
+            return
+
+        with self._lock:
+            if len(self._queue) == 0:
+                return
+            if time.monotonic() < self._retry_after:
+                return
+
+        self._flushing = True
+        try:
+            self._do_flush()
+        finally:
+            self._flushing = False
+
+    def flush_all(self) -> None:
+        """Flush the entire queue in batches.
+
+        Resets backoff state before flushing.  Stops if the queue is not
+        shrinking (circuit breaker, mirrors ``queue.ts:121-124``).
+        """
+        self._retry_after = 0.0
+        self._failure_count = 0
+        while True:
+            with self._lock:
+                size_before = len(self._queue)
+            if size_before == 0:
+                break
+            self.flush()
+            with self._lock:
+                size_after = len(self._queue)
+            if size_after >= size_before:
+                break
+
+    def shutdown(self, timeout: float = 30.0) -> None:
+        """Stop the timer and flush all remaining events.
+
+        Parameters
+        ----------
+        timeout:
+            Maximum seconds to wait for the timer thread to join.
+        """
+        self.stop()
+        if self.size == 0:
+            return
+        self.flush_all()
+        if self._timer_thread is not None:
+            self._timer_thread.join(timeout=timeout)
+
+    @property
+    def size(self) -> int:
+        """Number of events in the queue (does not include in-flight)."""
+        with self._lock:
+            return len(self._queue)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _flush_loop(self) -> None:
+        """Background loop: sleep for ``flush_interval``, then flush."""
+        while not self._stop_event.is_set():
+            self._flush_now_event.clear()
+            # Wait for either the interval to elapse or an explicit trigger
+            self._stop_event.wait(timeout=self._flush_interval)
+            if self._stop_event.is_set():
+                break
+            self.flush()
+
+    def _do_flush(self) -> None:
+        """Execute a single flush cycle (extract batch, send, handle result)."""
+        with self._lock:
+            if len(self._queue) == 0:
+                return
+            batch: List[Dict[str, Any]] = []
+            for _ in range(min(self._flush_size, len(self._queue))):
+                batch.append(self._queue.popleft())
+
+        envelope = {
+            "events": batch,
+            "sent_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+            + "Z",
+        }
+
+        try:
+            ok = self._transport.send(
+                self._endpoint,
+                self._api_key,
+                envelope,
+                timeout=self._timeout,
+            )
+            if ok:
+                self._failure_count = 0
+                self._retry_after = 0.0
+            else:
+                # Transport returned False — re-queue and backoff
+                with self._lock:
+                    self._queue.extendleft(reversed(batch))
+                self._schedule_backoff()
+                if self._logger:
+                    backoff = min(
+                        1.0 * 2 ** (self._failure_count - 1), self._max_backoff
+                    )
+                    self._logger(
+                        f"flush failed, {len(batch)} events re-queued, "
+                        f"retry in {backoff:.0f}s"
+                    )
+        except QuotaExceededError:
+            with self._lock:
+                self._queue.clear()
+            self._stopped_permanently = True
+            self.stop()
+            if self._logger:
+                self._logger("quota exceeded, events dropped and queue stopped")
+        except NonRetryableError as exc:
+            # Drop the batch — retrying won't help
+            if self._logger:
+                self._logger(
+                    f"non-retryable error ({exc.status_code}), "
+                    f"{len(batch)} events dropped"
+                )
+        except Exception:
+            # 5xx / network error — re-queue and backoff
+            with self._lock:
+                self._queue.extendleft(reversed(batch))
+            self._schedule_backoff()
+            if self._logger:
+                self._logger(
+                    f"flush error, {len(batch)} events re-queued"
+                )
+
+    def _schedule_backoff(self) -> None:
+        """Increment failure count and compute next retry-after timestamp."""
+        self._failure_count += 1
+        backoff = min(1.0 * 2 ** (self._failure_count - 1), self._max_backoff)
+        self._retry_after = time.monotonic() + backoff