whisperr 0.1.0__tar.gz

whisperr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

whisperr-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+# Publishes whisperr to PyPI when a version tag is pushed:
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Auth: PyPI Trusted Publishing (OIDC) — NO stored token. Before the first
+# publish, configure a Trusted Publisher for the `whisperr` project on pypi.org
+# (Publishing → Add a new pending publisher: owner WhisperrAI, repo
+# whisperr-python, workflow publish.yml, environment pypi).
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write # required for PyPI trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

whisperr-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

whisperr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Whisperr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whisperr-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: whisperr
+Version: 0.1.0
+Summary: Whisperr server-side SDK for Python — reliable churn-signal event tracking.
+Project-URL: Homepage, https://whisperr.net
+Project-URL: Repository, https://github.com/WhisperrAI/whisperr-python
+Author: Whisperr
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,churn,events,retention,tracking,whisperr
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: django>=3.2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Description-Content-Type: text/markdown
+
+# whisperr (Python)
+
+The Whisperr **server-side** SDK for Python — reliable churn-signal event
+tracking for any Python backend. The backend is where the highest-signal churn
+events live (payment failures, cancellations, trial expiry, usage drops), so
+this is where Whisperr gets its most valuable signal.
+
+```bash
+pip install whisperr
+```
+
+## Quick start
+
+```python
+import os
+from whisperr import Whisperr
+
+whisperr = Whisperr(api_key=os.environ["WHISPERR_API_KEY"])
+
+# A server-side churn signal:
+whisperr.track("user_8842", "payment_failed", {"amount_cents": 4900, "reason": "card_declined"})
+
+# Associate traits / contact channels with a user:
+whisperr.identify("user_8842", email="ada@example.com", traits={"plan": "pro"})
+
+# Deliver everything before the process exits:
+whisperr.shutdown()
+```
+
+The user id (`external_user_id`) is **always explicit** here — unlike a browser
+SDK, the server has no persisted session to infer it from. Pass the same id you
+use everywhere else for that user, and frontend + backend events land on one
+timeline automatically.
+
+## Design
+
+- **Same wire contract as the other Whisperr SDKs.** Events post to
+  `/v1/events/batch`, identities to `/v1/identify`, authenticated with
+  `X-API-Key`.
+- **Non-blocking.** `track()`/`identify()` enqueue and return immediately; a
+  background thread batches and delivers. Call `flush()` for a barrier.
+- **Reliable in-process.** In-memory queue, batching, retry with backoff
+  (429/5xx), malformed-4xx drop, per-event idempotency key. On `401/403` or
+  exhausted retries, delivery pauses and **events stay buffered for the next
+  flush** rather than being dropped. The queue is not crash-durable — call
+  `flush()`/`shutdown()` before exit (see *Short-lived processes*).
+- **Process-friendly.** A daemon thread that never blocks exit; `shutdown()` is
+  also registered via `atexit`.
+- **Zero runtime dependencies.** Uses the standard library only.
+
+## Django
+
+```python
+# settings.py
+WHISPERR_API_KEY = os.environ["WHISPERR_API_KEY"]
+MIDDLEWARE = [
+    # ... after your authentication middleware ...
+    "whisperr.django.WhisperrMiddleware",
+]
+```
+
+```python
+# views.py
+def upgrade(request):
+    request.whisperr.track("plan_upgraded", {"plan": "pro"})
+    ...
+```
+
+`request.whisperr.track()` is bound to the request's authenticated user
+(`request.user.pk` by default; override with `WHISPERR_RESOLVE_USER`, a dotted
+path to `def resolve(request) -> str | None`). For events with no request —
+Celery tasks, webhooks, management commands — use a client directly with the
+user id from your domain data:
+
+```python
+from whisperr.django import get_client
+get_client().track(subscription.user_id, "subscription_cancelled", {"reason": reason})
+```
+
+Install the Django extra if you want the dependency pinned: `pip install whisperr[django]`.
+
+## Short-lived processes
+
+In scripts, serverless handlers, or management commands, call `flush()` (or
+`shutdown()`) before exit so queued events aren't lost:
+
+```python
+whisperr.track(user_id, "report_generated")
+whisperr.flush()
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `api_key` | — | App ingestion key (`wrk_…`). Required. |
+| `base_url` | `https://api.whisperr.net` | Ingestion base URL. |
+| `flush_at` | `20` | Flush when this many events are queued. |
+| `flush_interval` | `10.0` | Background flush cadence (seconds). |
+| `max_queue_size` | `10000` | Oldest events drop on overflow. |
+| `max_batch_size` | `500` | Events per batch (hard backend cap is 500). |
+| `max_retries` | `6` | Consecutive retries before giving up a batch. |
+| `request_timeout` | `10.0` | Per-request timeout (seconds). |
+| `disabled` | `False` | No-op client (useful in tests). |
+| `debug` | `False` | Verbose logging to stderr. |
+| `on_error` | — | `Callable[[WhisperrError], None]` for observability. |
+
+---
+
+Whisperr — predict churn, automate interventions, recover revenue.
+[whisperr.net](https://whisperr.net)

whisperr-0.1.0/README.md

@@ -0,0 +1,111 @@
+# whisperr (Python)
+
+The Whisperr **server-side** SDK for Python — reliable churn-signal event
+tracking for any Python backend. The backend is where the highest-signal churn
+events live (payment failures, cancellations, trial expiry, usage drops), so
+this is where Whisperr gets its most valuable signal.
+
+```bash
+pip install whisperr
+```
+
+## Quick start
+
+```python
+import os
+from whisperr import Whisperr
+
+whisperr = Whisperr(api_key=os.environ["WHISPERR_API_KEY"])
+
+# A server-side churn signal:
+whisperr.track("user_8842", "payment_failed", {"amount_cents": 4900, "reason": "card_declined"})
+
+# Associate traits / contact channels with a user:
+whisperr.identify("user_8842", email="ada@example.com", traits={"plan": "pro"})
+
+# Deliver everything before the process exits:
+whisperr.shutdown()
+```
+
+The user id (`external_user_id`) is **always explicit** here — unlike a browser
+SDK, the server has no persisted session to infer it from. Pass the same id you
+use everywhere else for that user, and frontend + backend events land on one
+timeline automatically.
+
+## Design
+
+- **Same wire contract as the other Whisperr SDKs.** Events post to
+  `/v1/events/batch`, identities to `/v1/identify`, authenticated with
+  `X-API-Key`.
+- **Non-blocking.** `track()`/`identify()` enqueue and return immediately; a
+  background thread batches and delivers. Call `flush()` for a barrier.
+- **Reliable in-process.** In-memory queue, batching, retry with backoff
+  (429/5xx), malformed-4xx drop, per-event idempotency key. On `401/403` or
+  exhausted retries, delivery pauses and **events stay buffered for the next
+  flush** rather than being dropped. The queue is not crash-durable — call
+  `flush()`/`shutdown()` before exit (see *Short-lived processes*).
+- **Process-friendly.** A daemon thread that never blocks exit; `shutdown()` is
+  also registered via `atexit`.
+- **Zero runtime dependencies.** Uses the standard library only.
+
+## Django
+
+```python
+# settings.py
+WHISPERR_API_KEY = os.environ["WHISPERR_API_KEY"]
+MIDDLEWARE = [
+    # ... after your authentication middleware ...
+    "whisperr.django.WhisperrMiddleware",
+]
+```
+
+```python
+# views.py
+def upgrade(request):
+    request.whisperr.track("plan_upgraded", {"plan": "pro"})
+    ...
+```
+
+`request.whisperr.track()` is bound to the request's authenticated user
+(`request.user.pk` by default; override with `WHISPERR_RESOLVE_USER`, a dotted
+path to `def resolve(request) -> str | None`). For events with no request —
+Celery tasks, webhooks, management commands — use a client directly with the
+user id from your domain data:
+
+```python
+from whisperr.django import get_client
+get_client().track(subscription.user_id, "subscription_cancelled", {"reason": reason})
+```
+
+Install the Django extra if you want the dependency pinned: `pip install whisperr[django]`.
+
+## Short-lived processes
+
+In scripts, serverless handlers, or management commands, call `flush()` (or
+`shutdown()`) before exit so queued events aren't lost:
+
+```python
+whisperr.track(user_id, "report_generated")
+whisperr.flush()
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `api_key` | — | App ingestion key (`wrk_…`). Required. |
+| `base_url` | `https://api.whisperr.net` | Ingestion base URL. |
+| `flush_at` | `20` | Flush when this many events are queued. |
+| `flush_interval` | `10.0` | Background flush cadence (seconds). |
+| `max_queue_size` | `10000` | Oldest events drop on overflow. |
+| `max_batch_size` | `500` | Events per batch (hard backend cap is 500). |
+| `max_retries` | `6` | Consecutive retries before giving up a batch. |
+| `request_timeout` | `10.0` | Per-request timeout (seconds). |
+| `disabled` | `False` | No-op client (useful in tests). |
+| `debug` | `False` | Verbose logging to stderr. |
+| `on_error` | — | `Callable[[WhisperrError], None]` for observability. |
+
+---
+
+Whisperr — predict churn, automate interventions, recover revenue.
+[whisperr.net](https://whisperr.net)

whisperr-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "whisperr"
+dynamic = ["version"]
+description = "Whisperr server-side SDK for Python — reliable churn-signal event tracking."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "Whisperr" }]
+keywords = ["whisperr", "analytics", "churn", "events", "tracking", "retention"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://whisperr.net"
+Repository = "https://github.com/WhisperrAI/whisperr-python"
+
+[project.optional-dependencies]
+django = ["django>=3.2"]
+dev = ["pytest>=7", "django>=3.2"]
+
+[tool.hatch.version]
+path = "src/whisperr/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/whisperr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

whisperr-0.1.0/src/whisperr/__init__.py

@@ -0,0 +1,18 @@
+"""Whisperr server-side SDK for Python.
+
+Reliable churn-signal event tracking for any Python backend. The backend is
+where the highest-signal churn events live (payment failures, cancellations,
+trial expiry, usage drops), so this is where Whisperr gets its best signal.
+
+    from whisperr import Whisperr
+
+    whisperr = Whisperr(api_key=os.environ["WHISPERR_API_KEY"])
+    whisperr.track("user_8842", "payment_failed", {"amount_cents": 4900})
+    whisperr.shutdown()  # flush before the process exits
+"""
+
+from .client import Whisperr
+from .errors import WhisperrError
+
+__all__ = ["Whisperr", "WhisperrError", "__version__"]
+__version__ = "0.1.0"

whisperr-0.1.0/src/whisperr/client.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import atexit
+import random
+import re
+import sys
+import threading
+import time
+import uuid
+from collections import deque
+from datetime import datetime, timezone
+from typing import Any, Callable, Deque, Dict, List, Optional, Sequence
+
+from .errors import WhisperrError
+from .transport import Transport
+
+DEFAULT_BASE = "https://api.whisperr.net"
+# Mirrors the server's accepted event_type shape.
+_SNAKE = re.compile(r"^[a-z0-9]+(?:_[a-z0-9]+)*$")
+
+Channel = Dict[str, Any]
+OnError = Callable[[WhisperrError], None]
+
+
+class Whisperr:
+    """A Whisperr client for a Python backend.
+
+    Hold one instance per process and call :meth:`shutdown` before exit (also
+    registered via ``atexit``). ``track``/``identify`` are non-blocking: they
+    enqueue and a background thread batches + delivers with retries.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE,
+        flush_at: int = 20,
+        flush_interval: float = 10.0,
+        max_queue_size: int = 10000,
+        max_batch_size: int = 500,
+        max_retries: int = 6,
+        request_timeout: float = 10.0,
+        disabled: bool = False,
+        debug: bool = False,
+        on_error: Optional[OnError] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not api_key and not disabled:
+            raise ValueError("api_key is required")
+        self._muted = bool(disabled)
+        self._flush_at = flush_at
+        self._max_batch = min(max_batch_size, 500)
+        self._max_queue = max_queue_size
+        self._max_retries = max_retries
+        self._debug = debug
+        self._on_error = on_error
+        self._flush_interval = flush_interval
+        self._transport = transport or Transport(base_url, api_key, request_timeout, self._warn)
+
+        # Ordered in-memory buffer. A drain pass takes a batch off the front,
+        # delivers it, and only puts it back (at the front) if delivery gives up —
+        # so a failed flush *retains* events for the next flush instead of
+        # dropping them. There's no durable store: a process crash loses unsent
+        # events, which is an acceptable trade for zero I/O on the hot path.
+        self._buf: Deque[Dict[str, Any]] = deque()
+        self._buf_lock = threading.Lock()
+        # Serializes delivery so the background thread and an explicit flush()
+        # never send concurrently (and never fight over the same batch).
+        self._deliver_lock = threading.Lock()
+        self._wake = threading.Event()
+
+        self._running = not self._muted
+        self._thread: Optional[threading.Thread] = None
+
+        if not self._muted:
+            self._thread = threading.Thread(target=self._run, name="whisperr", daemon=True)
+            self._thread.start()
+            atexit.register(self.shutdown)
+
+    @property
+    def ready(self) -> bool:
+        return not self._muted
+
+    def identify(
+        self,
+        external_user_id: str,
+        *,
+        traits: Optional[Dict[str, Any]] = None,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        push_token: Optional[str] = None,
+        preferred_channel: Optional[str] = None,
+        channels: Optional[Sequence[Channel]] = None,
+    ) -> None:
+        """Associate traits/contact channels with a user. ``external_user_id``
+        is always explicit — pass the same id you use in :meth:`track`."""
+        if self._muted or not external_user_id:
+            return
+        self._enqueue(
+            {
+                "kind": "identify",
+                "external_user_id": external_user_id,
+                "traits": traits,
+                "preferred_channel": preferred_channel,
+                "channels": list(channels)
+                if channels is not None
+                else _build_channels(email, phone, push_token),
+            }
+        )
+
+    def track(
+        self,
+        external_user_id: str,
+        event_type: str,
+        properties: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record a product event for a known user."""
+        if self._muted or not external_user_id or not event_type:
+            return
+        if self._debug and not _SNAKE.match(event_type):
+            self._warn(f'event_type "{event_type}" is not snake_case — the server will reject it')
+        self._enqueue(
+            {
+                "kind": "track",
+                "external_user_id": external_user_id,
+                "event_type": event_type,
+                "properties": properties,
+                "context": context,
+                "occurred_at": _now_iso(),
+                "message_id": uuid.uuid4().hex,
+            }
+        )
+
+    def flush(self) -> None:
+        """Best-effort barrier: deliver everything currently buffered, blocking
+        until the buffer drains or delivery can't proceed (auth/transport
+        failure). Events that can't be delivered stay buffered for the next
+        flush rather than being dropped."""
+        if self._muted:
+            return
+        self._drain_once()
+
+    def shutdown(self) -> None:
+        """Stop the background thread after a final delivery pass. Idempotent."""
+        if self._muted or not self._running:
+            return
+        self._running = False
+        self._wake.set()
+        if self._thread is not None:
+            self._thread.join()
+
+    # ---- internals ----
+
+    def _enqueue(self, op: Dict[str, Any]) -> None:
+        dropped = 0
+        with self._buf_lock:
+            self._buf.append(op)
+            while len(self._buf) > self._max_queue:
+                self._buf.popleft()
+                dropped += 1
+            size = len(self._buf)
+        if dropped:
+            self._emit("dropped", f"queue full — dropped {dropped} oldest event(s)")
+        # Wake the worker to flush early once enough has accumulated.
+        if size >= self._flush_at:
+            self._wake.set()
+
+    def _run(self) -> None:
+        # Periodic + size-triggered delivery. Always makes one final pass after
+        # shutdown so the loop can't spin on an undeliverable (retained) batch.
+        while True:
+            self._wake.wait(timeout=self._flush_interval)
+            self._wake.clear()
+            try:
+                self._drain_once()
+            except Exception:
+                pass  # never let the worker thread die on a delivery error
+            if not self._running:
+                return
+
+    def _take_batch(self) -> List[Dict[str, Any]]:
+        """Remove and return the next batch from the front of the buffer.
+
+        An identify is sent on its own; track ops are grouped into a leading run
+        (up to ``max_batch``). Returns ``[]`` when the buffer is empty."""
+        with self._buf_lock:
+            if not self._buf:
+                return []
+            if self._buf[0]["kind"] == "identify":
+                return [self._buf.popleft()]
+            batch: List[Dict[str, Any]] = []
+            while self._buf and len(batch) < self._max_batch and self._buf[0]["kind"] == "track":
+                batch.append(self._buf.popleft())
+            return batch
+
+    def _requeue_front(self, batch: List[Dict[str, Any]]) -> None:
+        with self._buf_lock:
+            self._buf.extendleft(reversed(batch))
+
+    def _drain_once(self) -> None:
+        # One delivery pass, serialized against the background thread.
+        with self._deliver_lock:
+            while True:
+                batch = self._take_batch()
+                if not batch:
+                    return
+                result = self._deliver(batch)
+                if result in ("ok", "drop"):
+                    continue
+                # auth / retry_exhausted: hand the batch back to the front and
+                # stop; a later flush retries from where we left off.
+                self._requeue_front(batch)
+                return
+
+    def _deliver(self, batch: List[Dict[str, Any]]) -> str:
+        if batch[0]["kind"] == "identify":
+            send: Callable[[], str] = lambda: self._transport.send_identify(batch[0])
+            count = 1
+        else:
+            send = lambda: self._transport.send_batch(batch)
+            count = len(batch)
+        retries = 0
+        while True:
+            result = send()
+            if result == "ok":
+                return "ok"
+            if result == "drop":
+                self._emit("dropped", f"dropped {count} event(s) — rejected by server")
+                return "drop"
+            if result == "auth":
+                self._emit("auth", "delivery paused — API key rejected", 401)
+                return "auth"
+            retries += 1
+            # Stop early when shutting down so exit isn't held up by backoff.
+            if retries > self._max_retries or not self._running:
+                self._emit("retry_exhausted", "delivery failed after retries; will retry on next flush")
+                return "retry_exhausted"
+            time.sleep(_backoff(retries))
+
+    def _emit(self, type_: str, message: str, status: Optional[int] = None) -> None:
+        if not self._on_error:
+            return
+        try:
+            self._on_error(WhisperrError(type=type_, message=message, status=status))
+        except Exception:
+            pass  # host callback threw — ignore
+
+    def _warn(self, msg: str) -> None:
+        if self._debug:
+            print(f"[whisperr] {msg}", file=sys.stderr)
+
+
+def _build_channels(
+    email: Optional[str], phone: Optional[str], push_token: Optional[str]
+) -> Optional[List[Channel]]:
+    out: List[Channel] = []
+    if email:
+        out.append({"type": "email", "address": email, "opted_in": True})
+    if phone:
+        out.append({"type": "sms", "address": phone, "opted_in": True})
+    if push_token:
+        out.append({"type": "push", "address": push_token, "opted_in": True})
+    return out or None
+
+
+def _backoff(attempt: int) -> float:
+    base = min(30.0, 1.0 * (2 ** attempt))
+    return base + random.random() * 0.25
+
+
+def _now_iso() -> str:
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"

whisperr-0.1.0/src/whisperr/django.py

@@ -0,0 +1,93 @@
+"""Django integration for Whisperr.
+
+Add to settings.py::
+
+    WHISPERR_API_KEY = os.environ["WHISPERR_API_KEY"]
+    MIDDLEWARE = [
+        # ... after your authentication middleware ...
+        "whisperr.django.WhisperrMiddleware",
+    ]
+
+Then in a view::
+
+    request.whisperr.track("plan_upgraded", {"plan": "pro"})
+
+For events with no request (Celery tasks, webhooks, management commands), use a
+client directly with the user id from your domain data.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Callable, Dict, Optional, Sequence
+
+from .client import Whisperr
+
+_client: Optional[Whisperr] = None
+
+
+def get_client() -> Whisperr:
+    """The process-wide Whisperr client, built from Django settings on first use."""
+    global _client
+    if _client is None:
+        from django.conf import settings
+
+        _client = Whisperr(
+            api_key=getattr(settings, "WHISPERR_API_KEY", ""),
+            base_url=getattr(settings, "WHISPERR_BASE_URL", "https://api.whisperr.net"),
+            disabled=getattr(settings, "WHISPERR_DISABLED", False),
+            debug=getattr(settings, "WHISPERR_DEBUG", False),
+        )
+    return _client
+
+
+class _RequestWhisperr:
+    """Per-request helper bound to the request's resolved user."""
+
+    def __init__(self, client: Whisperr, user_id: Optional[str]) -> None:
+        self.client = client
+        self.user_id = user_id
+
+    def track(
+        self,
+        event_type: str,
+        properties: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if not self.user_id:
+            return
+        self.client.track(self.user_id, event_type, properties, context)
+
+    def identify(self, **kwargs: Any) -> None:
+        if not self.user_id:
+            return
+        self.client.identify(self.user_id, **kwargs)
+
+
+def _default_resolve_user(request: Any) -> Optional[str]:
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        return str(user.pk)
+    return None
+
+
+def _import_callable(dotted: str) -> Callable[[Any], Optional[str]]:
+    module_path, _, attr = dotted.rpartition(".")
+    module = import_module(module_path)
+    return getattr(module, attr)
+
+
+class WhisperrMiddleware:
+    """Attaches ``request.whisperr`` bound to the request's user."""
+
+    def __init__(self, get_response: Callable[[Any], Any]) -> None:
+        self.get_response = get_response
+        self.client = get_client()
+        from django.conf import settings
+
+        resolver = getattr(settings, "WHISPERR_RESOLVE_USER", None)
+        self.resolve_user = _import_callable(resolver) if resolver else _default_resolve_user
+
+    def __call__(self, request: Any) -> Any:
+        request.whisperr = _RequestWhisperr(self.client, self.resolve_user(request))
+        return self.get_response(request)

whisperr-0.1.0/src/whisperr/errors.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class WhisperrError:
+    """Passed to the ``on_error`` callback for delivery/drop observability."""
+
+    type: str  # "auth" | "dropped" | "retry_exhausted"
+    message: str
+    status: Optional[int] = None

whisperr-0.1.0/src/whisperr/transport.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List
+
+# Delivery outcome of one request, mirroring the @whisperr/node SDK:
+#   "ok"    — delivered
+#   "retry" — transient (429, 5xx, network/timeout)
+#   "auth"  — key rejected (401/403); stop and surface
+#   "drop"  — other 4xx (malformed); discard to avoid an infinite retry loop
+SendResult = str
+
+
+class Transport:
+    """HTTP transport for the Whisperr ingestion API (stdlib urllib, zero deps)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float,
+        warn: Callable[[str], None],
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._key = api_key
+        self._timeout = timeout
+        self._warn = warn
+
+    def send_batch(self, events: List[Dict[str, Any]]) -> SendResult:
+        payload = {
+            "events": [
+                {
+                    "external_user_id": e["external_user_id"],
+                    "event_type": e["event_type"],
+                    "occurred_at": e["occurred_at"],
+                    "properties": e.get("properties") or {},
+                    # $message_id is an idempotency key for backend dedup, nested
+                    # in the free-form context so the strict ingestion accepts it.
+                    "context": {**(e.get("context") or {}), "$message_id": e["message_id"]},
+                }
+                for e in events
+            ]
+        }
+        if not payload["events"]:
+            return "ok"
+        return self._post("/v1/events/batch", payload)
+
+    def send_identify(self, op: Dict[str, Any]) -> SendResult:
+        body: Dict[str, Any] = {"external_user_id": op["external_user_id"]}
+        if op.get("traits"):
+            body["traits"] = op["traits"]
+        if op.get("preferred_channel"):
+            body["preferred_channel"] = op["preferred_channel"]
+        channels = op.get("channels")
+        if channels:
+            body["channels"] = [
+                {
+                    "channel": c["type"],
+                    "address": c["address"],
+                    "opted_in": c.get("opted_in", True),
+                    **({"verified": c["verified"]} if "verified" in c else {}),
+                }
+                for c in channels
+            ]
+        return self._post("/v1/identify", body)
+
+    def _post(self, path: str, body: Any) -> SendResult:
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            self._base + path,
+            data=data,
+            method="POST",
+            headers={"Content-Type": "application/json", "X-API-Key": self._key},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout):
+                return "ok"  # urlopen raises on >= 400, so reaching here is 2xx/3xx
+        except urllib.error.HTTPError as e:
+            if e.code in (401, 403):
+                self._warn(f"auth rejected ({e.code}) — check your Whisperr API key")
+                return "auth"
+            if e.code == 429 or e.code >= 500:
+                return "retry"
+            self._warn(f"request to {path} dropped ({e.code})")
+            return "drop"
+        except Exception:
+            # Network error / timeout — retry later.
+            return "retry"

whisperr-0.1.0/tests/test_client.py

@@ -0,0 +1,232 @@
+import json
+import urllib.error
+import urllib.request
+
+import pytest
+
+from whisperr import Whisperr, WhisperrError
+from whisperr.transport import Transport
+
+
+class FakeTransport:
+    """Records ops at the client boundary (before wire serialization)."""
+
+    def __init__(self, result="ok"):
+        self.result = result
+        self.batches = []
+        self.identifies = []
+
+    def send_batch(self, events):
+        self.batches.append([dict(e) for e in events])
+        return self.result
+
+    def send_identify(self, op):
+        self.identifies.append(dict(op))
+        return self.result
+
+
+def make_client(transport, **kwargs):
+    return Whisperr(
+        api_key="wrk_test",
+        transport=transport,
+        flush_interval=0.05,
+        **kwargs,
+    )
+
+
+# ---- client behavior ----
+
+def test_track_delivers_events_with_explicit_user_and_message_id():
+    t = FakeTransport()
+    w = make_client(t)
+    try:
+        w.track("user_8842", "payment_failed", {"amount_cents": 4900})
+        w.track("user_8842", "subscription_cancelled")
+        w.flush()
+    finally:
+        w.shutdown()
+
+    # Batching is opportunistic, so events may arrive in one or several batches —
+    # what matters is that all of them are delivered, correctly shaped.
+    events = [e for batch in t.batches for e in batch]
+    assert len(events) == 2
+    by_type = {e["event_type"]: e for e in events}
+    assert by_type["payment_failed"]["external_user_id"] == "user_8842"
+    assert by_type["payment_failed"]["properties"] == {"amount_cents": 4900}
+    assert by_type["payment_failed"]["occurred_at"].endswith("Z")
+    assert len({e["message_id"] for e in events}) == 2
+
+
+def test_bulk_delivery():
+    # All queued events are delivered exactly once (across however many batches).
+    t = FakeTransport()
+    w = Whisperr(api_key="wrk_test", transport=t, flush_interval=10.0)
+    try:
+        for i in range(50):
+            w.track("user_1", f"event_{i}")
+        w.flush()
+    finally:
+        w.shutdown()
+    delivered = [e for batch in t.batches for e in batch]
+    assert len(delivered) == 50
+    assert len({e["event_type"] for e in delivered}) == 50  # no dupes, none lost
+
+
+def test_identify_carries_traits_and_channels():
+    t = FakeTransport()
+    w = make_client(t)
+    try:
+        w.identify("user_8842", traits={"plan": "pro"}, email="a@b.com", preferred_channel="email")
+        w.flush()
+    finally:
+        w.shutdown()
+
+    assert len(t.identifies) == 1
+    op = t.identifies[0]
+    assert op["external_user_id"] == "user_8842"
+    assert op["traits"] == {"plan": "pro"}
+    assert op["preferred_channel"] == "email"
+    assert op["channels"] == [{"type": "email", "address": "a@b.com", "opted_in": True}]
+
+
+def test_track_requires_user_and_event_type():
+    t = FakeTransport()
+    w = make_client(t)
+    try:
+        w.track("", "payment_failed")
+        w.track("user_1", "")
+        w.flush()
+    finally:
+        w.shutdown()
+    assert t.batches == []
+
+
+def test_auth_failure_emits_and_stops():
+    t = FakeTransport(result="auth")
+    errors = []
+    w = make_client(t, on_error=errors.append)
+    try:
+        w.track("user_1", "feature_used")
+        w.flush()
+    finally:
+        w.shutdown()
+    assert any(e.type == "auth" for e in errors)
+
+
+def test_drop_on_4xx():
+    t = FakeTransport(result="drop")
+    errors = []
+    w = make_client(t, on_error=errors.append)
+    try:
+        w.track("user_1", "feature_used")
+        w.flush()
+    finally:
+        w.shutdown()
+    assert any(e.type == "dropped" for e in errors)
+
+
+def test_retry_exhausted_is_bounded():
+    t = FakeTransport(result="retry")
+    errors = []
+    w = make_client(t, on_error=errors.append, max_retries=0)
+    try:
+        w.track("user_1", "feature_used")
+        w.flush()
+    finally:
+        w.shutdown()
+    assert any(e.type == "retry_exhausted" for e in errors)
+
+
+def test_failed_events_are_retained_and_retried():
+    # A delivery that fails on auth must keep the events buffered so a later
+    # flush retries the SAME events — they must not be silently dropped.
+    t = FakeTransport(result="auth")
+    # High flush_interval so only our explicit flush() calls drive delivery.
+    w = Whisperr(api_key="wrk_test", transport=t, flush_interval=3600)
+    try:
+        w.track("user_1", "feature_used")
+        w.flush()  # auth → event retained, not delivered
+        attempts_before = len(t.batches)
+
+        t.result = "ok"
+        w.flush()  # retries the retained event, now succeeds
+        attempts_after = len(t.batches)
+    finally:
+        w.shutdown()
+
+    # The event was re-sent after the failure was fixed (retained), not dropped.
+    assert attempts_after == attempts_before + 1
+    assert [e["event_type"] for e in t.batches[-1]] == ["feature_used"]
+
+
+def test_disabled_is_noop():
+    t = FakeTransport()
+    w = Whisperr(api_key="wrk_test", transport=t, disabled=True)
+    assert w.ready is False
+    w.track("user_1", "feature_used")
+    w.flush()
+    w.shutdown()
+    assert t.batches == [] and t.identifies == []
+
+
+def test_missing_api_key_raises():
+    with pytest.raises(ValueError):
+        Whisperr(api_key="")
+
+
+# ---- transport wire mapping ----
+
+def _capture_urlopen(captured):
+    class FakeResp:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    def fake(req, timeout=None):
+        captured["url"] = req.full_url
+        captured["headers"] = {k.lower(): v for k, v in req.header_items()}
+        captured["body"] = json.loads(req.data.decode())
+        return FakeResp()
+
+    return fake
+
+
+def test_transport_batch_wire_shape(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(urllib.request, "urlopen", _capture_urlopen(captured))
+    t = Transport("https://api.whisperr.net/", "wrk_test", 10, lambda m: None)
+    result = t.send_batch(
+        [{"external_user_id": "u1", "event_type": "x", "occurred_at": "2026-01-01T00:00:00.000Z",
+          "properties": {"a": 1}, "context": {"k": "v"}, "message_id": "mid1"}]
+    )
+    assert result == "ok"
+    assert captured["url"] == "https://api.whisperr.net/v1/events/batch"
+    assert captured["headers"]["x-api-key"] == "wrk_test"
+    ev = captured["body"]["events"][0]
+    assert ev["external_user_id"] == "u1"
+    assert ev["context"] == {"k": "v", "$message_id": "mid1"}
+
+
+def test_transport_identify_channel_mapping(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(urllib.request, "urlopen", _capture_urlopen(captured))
+    t = Transport("https://api.whisperr.net", "wrk_test", 10, lambda m: None)
+    t.send_identify(
+        {"external_user_id": "u1", "traits": {"plan": "pro"},
+         "channels": [{"type": "email", "address": "a@b.com", "opted_in": True}]}
+    )
+    assert captured["url"] == "https://api.whisperr.net/v1/identify"
+    assert captured["body"]["channels"] == [{"channel": "email", "address": "a@b.com", "opted_in": True}]
+
+
+@pytest.mark.parametrize("code,expected", [(401, "auth"), (403, "auth"), (429, "retry"), (500, "retry"), (400, "drop"), (422, "drop")])
+def test_transport_status_classification(monkeypatch, code, expected):
+    def raiser(req, timeout=None):
+        raise urllib.error.HTTPError(req.full_url, code, "err", {}, None)
+
+    monkeypatch.setattr(urllib.request, "urlopen", raiser)
+    t = Transport("https://api.whisperr.net", "wrk_test", 10, lambda m: None)
+    assert t.send_batch([{"external_user_id": "u1", "event_type": "x",
+                          "occurred_at": "2026-01-01T00:00:00.000Z", "message_id": "m"}]) == expected

whisperr-0.1.0/tests/test_conformance.py

@@ -0,0 +1,86 @@
+import json
+import os
+import re
+import urllib.request
+
+from whisperr import Whisperr
+
+SPEC_URL = "https://raw.githubusercontent.com/WhisperrAI/whisperr-spec/main/conformance/wire.json"
+RFC3339_Z = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$")
+
+
+def load_spec():
+    local = os.environ.get("WHISPERR_SPEC_PATH")
+    if local:
+        with open(local) as f:
+            return json.load(f)
+    with urllib.request.urlopen(SPEC_URL, timeout=15) as r:
+        return json.loads(r.read())
+
+
+def apply_case(client, case):
+    s = case["scenario"]
+    if case["op"] == "track":
+        client.track(s["externalUserId"], s["eventType"], s.get("properties"))
+        return
+    channels = None
+    if s.get("channels"):
+        channels = []
+        for ch in s["channels"]:
+            c = {"type": ch["type"], "address": ch["address"], "opted_in": ch.get("optedIn", True)}
+            if "verified" in ch:
+                c["verified"] = ch["verified"]
+            channels.append(c)
+    client.identify(
+        s["externalUserId"],
+        traits=s.get("traits"),
+        email=s.get("email"),
+        phone=s.get("phone"),
+        push_token=s.get("pushToken"),
+        preferred_channel=s.get("preferredChannel"),
+        channels=channels,
+    )
+
+
+def test_wire_conformance(monkeypatch):
+    # Load the spec first, before we patch urlopen to capture SDK requests.
+    spec = load_spec()
+    assert spec["cases"], "spec has no cases"
+
+    captured = []
+
+    class FakeResp:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    def fake_urlopen(req, timeout=None):
+        captured.append({"url": req.full_url, "body": json.loads(req.data.decode())})
+        return FakeResp()
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    client = Whisperr(api_key="wrk_test", flush_interval=0.05)
+
+    for case in spec["cases"]:
+        captured.clear()
+        apply_case(client, case)
+        client.flush()
+
+        call = next((c for c in captured if c["url"].endswith(case["endpoint"])), None)
+        assert call is not None, f"{case['name']}: expected POST {case['endpoint']}"
+
+        if case["op"] == "track":
+            event = call["body"]["events"][0]
+            for k, v in case.get("expectedEvent", {}).items():
+                assert event[k] == v, f"{case['name']}.{k}"
+            for key in case.get("contextMustContain", []):
+                assert key in event["context"], f"{case['name']} context.{key}"
+            if case.get("occurredAtRfc3339Z"):
+                assert RFC3339_Z.match(event["occurred_at"]), event["occurred_at"]
+        else:
+            for k, v in case.get("expectedBody", {}).items():
+                assert call["body"][k] == v, f"{case['name']}.{k}"
+
+    client.shutdown()