qurvo-python 0.1.0__py3-none-any.whl

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/_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

qurvo/_transport.py

@@ -0,0 +1,105 @@
+"""HTTP transport for the Qurvo Python SDK.
+
+Mirrors ``@qurvo/sdk-core/src/fetch-transport.ts``.  Uses only stdlib
+(``urllib.request`` + ``gzip``) — no third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from qurvo._types import NonRetryableError, QuotaExceededError
+
+
+class HttpTransport:
+    """Sends event batches to the Qurvo ingest endpoint via HTTP POST.
+
+    Compresses the JSON body with gzip by default.  Status-code handling:
+
+    * **202** — success, return ``True``
+    * **200 + quota_limited** — raise :class:`QuotaExceededError`
+    * **4xx** — raise :class:`NonRetryableError` (bad data, drop the batch)
+    * **5xx / network error** — raise generic ``Exception`` (retryable)
+    """
+
+    def __init__(self, *, compress: bool = True) -> None:
+        self._compress = compress
+
+    def send(
+        self,
+        endpoint: str,
+        api_key: str,
+        payload: Any,
+        timeout: Optional[float] = None,
+    ) -> bool:
+        """Send *payload* (a JSON-serialisable object) to *endpoint*.
+
+        Returns ``True`` on success (HTTP 202).
+
+        Raises:
+            QuotaExceededError: project exceeded monthly event quota.
+            NonRetryableError: 4xx — bad request, should not be retried.
+            Exception: 5xx or network failure — caller should retry.
+        """
+        json_bytes = json.dumps(payload).encode("utf-8")
+
+        headers = {
+            "x-api-key": api_key,
+        }
+
+        if self._compress:
+            body = gzip.compress(json_bytes)
+            headers["Content-Type"] = "text/plain"
+            headers["Content-Encoding"] = "gzip"
+        else:
+            body = json_bytes
+            headers["Content-Type"] = "application/json"
+
+        request = urllib.request.Request(
+            endpoint,
+            data=body,
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            kwargs: dict[str, Any] = {}
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+            with urllib.request.urlopen(request, **kwargs) as response:
+                status = response.status
+                response_body = response.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            response_body = exc.read().decode("utf-8", errors="replace")
+        except (urllib.error.URLError, OSError) as exc:
+            raise Exception(f"Network error: {exc}") from exc  # noqa: TRY002
+
+        return self._handle_status(status, response_body)
+
+    @staticmethod
+    def _handle_status(status: int, body: str) -> bool:
+        """Map HTTP status to return value or exception."""
+        if status == 202:
+            return True
+
+        if status == 200:
+            # Ingest returns 200 + { quota_limited: true } when quota exceeded
+            try:
+                parsed = json.loads(body)
+                if isinstance(parsed, dict) and parsed.get("quota_limited"):
+                    raise QuotaExceededError()
+            except (json.JSONDecodeError, TypeError):
+                pass
+            # 200 without quota_limited is still a success
+            return True
+
+        if 400 <= status < 500:
+            raise NonRetryableError(status, f"HTTP {status}: {body}")
+
+        # 5xx — retryable server error
+        raise Exception(f"HTTP {status}: {body}")  # noqa: TRY002

qurvo/_types.py

@@ -0,0 +1,140 @@
+"""Data types and exceptions for the Qurvo Python SDK.
+
+Mirrors ``@qurvo/sdk-core/src/types.ts``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+LogFn = Callable[[str], None]
+
+
+@dataclass
+class EventContext:
+    """Contextual metadata attached to each event.
+
+    All fields are optional — the SDK or caller populates whichever are
+    available.  Mirrors the TypeScript ``EventContext`` interface.
+    """
+
+    session_id: Optional[str] = None
+    url: Optional[str] = None
+    referrer: Optional[str] = None
+    page_title: Optional[str] = None
+    page_path: Optional[str] = None
+    device_type: Optional[str] = None
+    browser: Optional[str] = None
+    browser_version: Optional[str] = None
+    os: Optional[str] = None
+    os_version: Optional[str] = None
+    screen_width: Optional[int] = None
+    screen_height: Optional[int] = None
+    language: Optional[str] = None
+    timezone: Optional[str] = None
+    sdk_name: Optional[str] = None
+    sdk_version: Optional[str] = None
+
+
+@dataclass
+class EventPayload:
+    """A single analytics event to be sent to the ingest endpoint.
+
+    Mirrors the TypeScript ``EventPayload`` interface and the Zod
+    ``TrackEventSchema`` used by ``apps/ingest``.
+    """
+
+    event: str
+    distinct_id: str
+    anonymous_id: Optional[str] = None
+    properties: Optional[Dict[str, Any]] = None
+    user_properties: Optional[Dict[str, Any]] = None
+    context: Optional[EventContext] = None
+    timestamp: Optional[str] = None
+    event_id: Optional[str] = None
+
+
+@dataclass
+class BatchEnvelope:
+    """Wrapper sent to ``POST /v1/batch``.
+
+    Matches the Zod ``BatchWrapperSchema`` on the ingest side.
+    """
+
+    events: List[EventPayload] = field(default_factory=list)
+    sent_at: Optional[str] = None
+
+
+@dataclass
+class SdkConfig:
+    """Configuration for the Qurvo SDK client."""
+
+    api_key: str
+    endpoint: str = "https://ingest.qurvo.io/v1/batch"
+    flush_interval: float = 5.0
+    flush_size: int = 20
+    max_queue_size: int = 1000
+    timeout: float = 10.0
+    logger: Optional[LogFn] = None
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class QuotaExceededError(Exception):
+    """Raised when the project has exceeded its monthly event quota.
+
+    The ingest API returns ``200 { quota_limited: true }`` in this case
+    (PostHog pattern — prevents SDK retries).
+    """
+
+    def __init__(self) -> None:
+        super().__init__("Monthly event limit exceeded")
+
+
+class NonRetryableError(Exception):
+    """Raised on 4xx responses — the batch is invalid and retrying won't help.
+
+    Carries the HTTP status code for diagnostics.
+    """
+
+    def __init__(self, status_code: int, message: str = "") -> None:
+        self.status_code = status_code
+        super().__init__(message or f"HTTP {status_code}")
+
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+
+def payload_to_dict(payload: EventPayload) -> Dict[str, Any]:
+    """Convert an ``EventPayload`` to a JSON-serialisable dict.
+
+    Filters out ``None`` values because the ingest Zod schemas use
+    ``.optional()`` which accepts *missing* keys but not explicit ``null``.
+    """
+    return _strip_none(asdict(payload))
+
+
+def envelope_to_dict(envelope: BatchEnvelope) -> Dict[str, Any]:
+    """Convert a ``BatchEnvelope`` to a JSON-serialisable dict."""
+    result: Dict[str, Any] = {
+        "events": [payload_to_dict(e) for e in envelope.events],
+    }
+    if envelope.sent_at is not None:
+        result["sent_at"] = envelope.sent_at
+    return result
+
+
+def _strip_none(d: Any) -> Any:
+    """Recursively remove keys whose value is ``None``."""
+    if isinstance(d, dict):
+        return {k: _strip_none(v) for k, v in d.items() if v is not None}
+    if isinstance(d, list):
+        return [_strip_none(item) for item in d]
+    return d

qurvo/client.py

@@ -0,0 +1,262 @@
+"""Public-facing Qurvo client class.
+
+Mirrors ``@qurvo/sdk-node/src/index.ts``.  Assembles types + transport +
+queue into a convenient high-level API.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+from qurvo._queue import EventQueue
+from qurvo._transport import HttpTransport
+from qurvo._types import EventPayload, LogFn, SdkConfig, payload_to_dict
+
+SDK_NAME = "qurvo-python"
+
+DEFAULT_ENDPOINT = "https://ingest.qurvo.pro"
+
+
+def _get_sdk_version() -> str:
+    """Return the installed package version, falling back to ``"0.0.0"``."""
+    try:
+        from importlib.metadata import version
+
+        return version("qurvo-python")
+    except Exception:  # noqa: BLE001
+        return "0.0.0"
+
+
+class Qurvo:
+    """Qurvo analytics client for Python.
+
+    Usage::
+
+        from qurvo import Qurvo
+
+        qurvo = Qurvo(api_key="qk_...")
+        qurvo.track("user-123", "purchase", {"amount": 99.99})
+        qurvo.identify("user-123", {"name": "John", "plan": "pro"})
+        qurvo.shutdown()
+
+    Parameters
+    ----------
+    api_key:
+        Project API key (starts with ``qk_``).
+    endpoint:
+        Ingest endpoint URL (default ``https://ingest.qurvo.pro``).
+    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 ``(message: str) -> None``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = DEFAULT_ENDPOINT,
+        flush_interval: float = 5.0,
+        flush_size: int = 20,
+        max_queue_size: int = 1000,
+        timeout: float = 30.0,
+        logger: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._endpoint = endpoint
+        self._logger = logger
+        self._sdk_version = _get_sdk_version()
+
+        transport = HttpTransport()
+        self._queue = EventQueue(
+            transport=transport,
+            endpoint=f"{endpoint.rstrip('/')}/v1/batch",
+            api_key=api_key,
+            flush_interval=flush_interval,
+            flush_size=flush_size,
+            max_queue_size=max_queue_size,
+            timeout=timeout,
+            logger=logger,
+        )
+        self._queue.start()
+
+    # ------------------------------------------------------------------
+    # Public methods
+    # ------------------------------------------------------------------
+
+    def track(
+        self,
+        distinct_id: str,
+        event: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track a custom event.
+
+        Parameters
+        ----------
+        distinct_id:
+            Unique identifier for the user.
+        event:
+            Event name (e.g. ``"purchase"``, ``"page_view"``).
+        properties:
+            Optional event properties dict.
+        """
+        payload = self._build_payload(
+            event=event,
+            distinct_id=distinct_id,
+            properties=properties,
+        )
+        self._enqueue(payload)
+
+    def identify(
+        self,
+        distinct_id: str,
+        user_properties: Dict[str, Any],
+        anonymous_id: Optional[str] = None,
+    ) -> None:
+        """Identify a user and set their properties.
+
+        Parameters
+        ----------
+        distinct_id:
+            Unique identifier for the user.
+        user_properties:
+            Properties to set on the user profile.
+        anonymous_id:
+            Optional anonymous ID to merge with the user.
+        """
+        payload = self._build_payload(
+            event="$identify",
+            distinct_id=distinct_id,
+            user_properties=user_properties,
+            anonymous_id=anonymous_id,
+        )
+        self._enqueue(payload)
+
+    def set(
+        self,
+        distinct_id: str,
+        properties: Dict[str, Any],
+    ) -> None:
+        """Set user properties (overwrites existing values).
+
+        Uses the ``$set`` envelope pattern matching ``@qurvo/sdk-node``.
+
+        Parameters
+        ----------
+        distinct_id:
+            Unique identifier for the user.
+        properties:
+            Properties to set on the user profile.
+        """
+        payload = self._build_payload(
+            event="$set",
+            distinct_id=distinct_id,
+            user_properties={"$set": properties},
+        )
+        self._enqueue(payload)
+
+    def set_once(
+        self,
+        distinct_id: str,
+        properties: Dict[str, Any],
+    ) -> None:
+        """Set user properties only if they are not already set.
+
+        Uses the ``$set_once`` envelope pattern matching ``@qurvo/sdk-node``.
+
+        Parameters
+        ----------
+        distinct_id:
+            Unique identifier for the user.
+        properties:
+            Properties to set on the user profile (only if not already set).
+        """
+        payload = self._build_payload(
+            event="$set_once",
+            distinct_id=distinct_id,
+            user_properties={"$set_once": properties},
+        )
+        self._enqueue(payload)
+
+    def screen(
+        self,
+        distinct_id: str,
+        screen_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track a screen view event.
+
+        Parameters
+        ----------
+        distinct_id:
+            Unique identifier for the user.
+        screen_name:
+            Name of the screen being viewed.
+        properties:
+            Optional additional properties.
+        """
+        merged_properties: Dict[str, Any] = {"$screen_name": screen_name}
+        if properties:
+            merged_properties.update(properties)
+
+        payload = self._build_payload(
+            event="$screen",
+            distinct_id=distinct_id,
+            properties=merged_properties,
+        )
+        self._enqueue(payload)
+
+    def shutdown(self, timeout: float = 30.0) -> None:
+        """Gracefully flush remaining events and stop the background thread.
+
+        Parameters
+        ----------
+        timeout:
+            Maximum seconds to wait for the flush thread to finish.
+        """
+        self._queue.shutdown(timeout=timeout)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _build_payload(
+        self,
+        *,
+        event: str,
+        distinct_id: str,
+        properties: Optional[Dict[str, Any]] = None,
+        user_properties: Optional[Dict[str, Any]] = None,
+        anonymous_id: Optional[str] = None,
+    ) -> EventPayload:
+        """Build an ``EventPayload`` with SDK context, timestamp, and event_id."""
+        return EventPayload(
+            event=event,
+            distinct_id=str(distinct_id),
+            anonymous_id=anonymous_id,
+            properties=properties,
+            user_properties=user_properties,
+            context=None,
+            timestamp=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+            + "Z",
+            event_id=str(uuid.uuid4()),
+        )
+
+    def _enqueue(self, payload: EventPayload) -> None:
+        """Convert payload to dict and enqueue for batched sending."""
+        from qurvo._types import EventContext
+
+        # Attach SDK context
+        payload.context = EventContext(
+            sdk_name=SDK_NAME,
+            sdk_version=self._sdk_version,
+        )
+        self._queue.enqueue(payload_to_dict(payload))

qurvo_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+qurvo/__init__.py,sha256=GPhglBhdX5J-R2IKEPhTRTUk1Csao1g4W2k5tHF5Lpo,527
+qurvo/_queue.py,sha256=43fPDrdg9gMiCW3sVOX_75ibTlqcnI5oZOlglegj_Bs,8912
+qurvo/_transport.py,sha256=q_qDmNRXVHBJ4vNoq51pkA-uu45R0rHlO2TtiHidH5I,3498
+qurvo/_types.py,sha256=VfbdKlT4hEu5dJHxVGoNH4C_KuC5gUXLELqRVNWbFsk,4117
+qurvo/client.py,sha256=2G95X6w6XqUZynHpumrvj1bIZ052e1Dq32DnwbIzM-o,7664
+qurvo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qurvo_python-0.1.0.dist-info/METADATA,sha256=P02dboDRABiUk6coVHlvTqPlt9dKu4IbeZ6roHbq5Rc,3117
+qurvo_python-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+qurvo_python-0.1.0.dist-info/RECORD,,

qurvo_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any