redpennon 1.0.0__tar.gz

redpennon-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+*.pyc
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.python-version
+.venv/
+venv/
+node_modules/
+dist/
+coverage/
+*.egg-info/
+.coverage
+htmlcov/

redpennon-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: redpennon
+Version: 1.0.0
+Summary: RedPennon feature flag evaluation API client
+Project-URL: Homepage, https://redpennon.dev
+Project-URL: Documentation, https://docs.redpennon.dev
+Project-URL: Repository, https://github.com/redpennon/sdks
+Project-URL: Bug Tracker, https://github.com/redpennon/sdks/issues
+License-Expression: MIT
+Keywords: feature-flags,feature-toggles,redpennon
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# redpennon · Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/redpennon)](https://pypi.org/project/redpennon/)
+[![Python](https://img.shields.io/pypi/pyversions/redpennon)](https://pypi.org/project/redpennon/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/redpennon/sdks/blob/main/LICENSE)
+
+Thin HTTP client for the [RedPennon](https://redpennon.dev) feature flag evaluation API.
+
+## Installation
+
+```bash
+pip install redpennon
+```
+
+Requires Python 3.12+ and [`httpx`](https://www.python-httpx.org/).
+
+## Quick start
+
+```python
+from redpennon import Client, UserContext
+
+client = Client(api_key="YOUR_ENV_API_KEY")
+
+# Simple: get the resolved value or your default on any failure.
+enabled = client.variable_value("dark-mode-enabled", default=False)
+
+# With user context (for targeting rules).
+user = UserContext(id="user_123", email="alice@example.com")
+enabled = client.variable_value("dark-mode-enabled", default=False, user=user)
+
+# Full result: value + variation + reason.
+result = client.variable("dark-mode-enabled", user=user)
+print(result.value, result.variation, result.reason)
+
+# Batch: resolve many flags in one round-trip.
+results = client.variables(["flag-a", "flag-b"], user=user)
+flag_a = results["flag-a"].value
+```
+
+## API
+
+### `Client(api_key, *, base_url=None, http_client=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `api_key` | `str` | Environment API key from the RedPennon dashboard. |
+| `base_url` | `str \| None` | Override the API base URL (default: `https://api.redpennon.dev`). |
+| `http_client` | `httpx.Client \| None` | Custom client — useful for testing with `MockTransport`. |
+
+### `client.variable_value(key, *, default, user=None) → T`
+
+Returns the resolved value or `default` on any failure (network error, non-2xx, `value=null`). Use this in production code — your default is the load-bearing contract.
+
+### `client.variable(key, *, user=None) → VariableResult`
+
+Returns the full evaluation result (`value`, `variation`, `reason`, `feature`). Raises `APIError` on network or non-2xx errors.
+
+### `client.variables(keys, *, user=None) → dict[str, VariableResult]`
+
+Batch evaluation — one HTTP round-trip for multiple flags. Unknown keys return `reason="variable_not_found"` inline rather than raising.
+
+## Local development
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+## License
+
+[MIT](../LICENSE) © RedPennon

redpennon-1.0.0/README.md

@@ -0,0 +1,71 @@
+# redpennon · Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/redpennon)](https://pypi.org/project/redpennon/)
+[![Python](https://img.shields.io/pypi/pyversions/redpennon)](https://pypi.org/project/redpennon/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/redpennon/sdks/blob/main/LICENSE)
+
+Thin HTTP client for the [RedPennon](https://redpennon.dev) feature flag evaluation API.
+
+## Installation
+
+```bash
+pip install redpennon
+```
+
+Requires Python 3.12+ and [`httpx`](https://www.python-httpx.org/).
+
+## Quick start
+
+```python
+from redpennon import Client, UserContext
+
+client = Client(api_key="YOUR_ENV_API_KEY")
+
+# Simple: get the resolved value or your default on any failure.
+enabled = client.variable_value("dark-mode-enabled", default=False)
+
+# With user context (for targeting rules).
+user = UserContext(id="user_123", email="alice@example.com")
+enabled = client.variable_value("dark-mode-enabled", default=False, user=user)
+
+# Full result: value + variation + reason.
+result = client.variable("dark-mode-enabled", user=user)
+print(result.value, result.variation, result.reason)
+
+# Batch: resolve many flags in one round-trip.
+results = client.variables(["flag-a", "flag-b"], user=user)
+flag_a = results["flag-a"].value
+```
+
+## API
+
+### `Client(api_key, *, base_url=None, http_client=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `api_key` | `str` | Environment API key from the RedPennon dashboard. |
+| `base_url` | `str \| None` | Override the API base URL (default: `https://api.redpennon.dev`). |
+| `http_client` | `httpx.Client \| None` | Custom client — useful for testing with `MockTransport`. |
+
+### `client.variable_value(key, *, default, user=None) → T`
+
+Returns the resolved value or `default` on any failure (network error, non-2xx, `value=null`). Use this in production code — your default is the load-bearing contract.
+
+### `client.variable(key, *, user=None) → VariableResult`
+
+Returns the full evaluation result (`value`, `variation`, `reason`, `feature`). Raises `APIError` on network or non-2xx errors.
+
+### `client.variables(keys, *, user=None) → dict[str, VariableResult]`
+
+Batch evaluation — one HTTP round-trip for multiple flags. Unknown keys return `reason="variable_not_found"` inline rather than raising.
+
+## Local development
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+## License
+
+[MIT](../LICENSE) © RedPennon

redpennon-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "redpennon"
+version = "1.0.0"
+description = "RedPennon feature flag evaluation API client"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+keywords = ["feature-flags", "feature-toggles", "redpennon"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://redpennon.dev"
+Documentation = "https://docs.redpennon.dev"
+Repository = "https://github.com/redpennon/sdks"
+"Bug Tracker" = "https://github.com/redpennon/sdks/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+  "pytest-cov>=5,<6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/redpennon"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --cov=redpennon --cov-report=term-missing --cov-fail-under=80"
+
+[tool.coverage.run]
+branch = true
+source = ["redpennon"]
+
+[tool.coverage.report]
+omit = ["*/tests/*"]

redpennon-1.0.0/src/redpennon/__init__.py

@@ -0,0 +1,30 @@
+"""RedPennon API client."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from redpennon.client import (
+    APIError,
+    Client,
+    DEFAULT_API_BASE_URL,
+    EvaluationReason,
+    EventPayload,
+    TrackEventsResult,
+    UserContext,
+    VariableResult,
+)
+
+__all__ = [
+    "APIError",
+    "Client",
+    "DEFAULT_API_BASE_URL",
+    "EvaluationReason",
+    "EventPayload",
+    "TrackEventsResult",
+    "UserContext",
+    "VariableResult",
+]
+
+try:
+    __version__ = _pkg_version("redpennon")
+except PackageNotFoundError:  # pragma: no cover - source checkouts
+    __version__ = "0.0.0+unknown"

redpennon-1.0.0/src/redpennon/client.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Iterable, Literal, Mapping, Sequence, TypeVar
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_API_BASE_URL = "https://api.redpennon.dev"
+
+_LOG = logging.getLogger("redpennon")
+
+T = TypeVar("T")
+
+EvaluationReason = Literal[
+    "targeting_rule_matched",
+    "default_variation",
+    "no_rule_matched",
+    "targeting_disabled",
+    "feature_complete",
+    "feature_deleted",
+    "feature_archived",
+    "self_targeting_override",
+    "variable_not_found",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class UserContext:
+    """Targeting context the SDK forwards to the server.
+
+    ``app_version``, ``platform``, and ``country`` are built-ins that
+    most flag platforms auto-populate from a client-side SDK runtime.
+    Server-side SDKs can't reliably detect any of them — populate them
+    manually from your request context (e.g. parsed from a User-Agent
+    header or a CDN-supplied geo header) if you want to target on
+    them.
+
+    ``custom_data`` carries arbitrary attributes for targeting
+    conditions of type ``custom_property``; keys are looked up by the
+    rule's ``custom_key`` and values may be scalars or list-of-strings.
+    On the wire it serialises as ``custom_data``.
+    """
+
+    id: str | None = None
+    email: str | None = None
+    organisation_id: str | None = None
+    ip: str | None = None
+    audiences: Sequence[str] | None = None
+    app_version: str | None = None
+    platform: str | None = None
+    country: str | None = None
+    custom_data: Mapping[str, Any] | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.id is not None:
+            out["id"] = self.id
+        if self.email is not None:
+            out["email"] = self.email
+        if self.organisation_id is not None:
+            out["organisation_id"] = self.organisation_id
+        if self.ip is not None:
+            out["ip"] = self.ip
+        if self.audiences is not None:
+            out["audiences"] = list(self.audiences)
+        if self.app_version is not None:
+            out["app_version"] = self.app_version
+        if self.platform is not None:
+            out["platform"] = self.platform
+        if self.country is not None:
+            out["country"] = self.country
+        if self.custom_data is not None:
+            out["custom_data"] = dict(self.custom_data)
+        return out
+
+
+class APIError(Exception):
+    """Raised by ``Client.variable`` / ``Client.variables`` on non-2xx
+    responses or transport errors. ``Client.variable_value`` swallows
+    these and substitutes the caller's default.
+
+    ``code`` mirrors the platform's governance error vocabulary
+    (``rate_limit_exceeded``, ``organisation_suspended``,
+    ``monthly_active_users_exceeded`` …) when the response body carries
+    a structured ``{"error", "code"}`` payload. ``None`` for transport
+    errors or unstructured responses; callers branching on governance
+    state should match on ``code``, not ``message``.
+    """
+
+    def __init__(self, status_code: int, message: str, code: str | None = None) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.code = code
+        super().__init__(f"redpennon: api error {status_code}: {message}")
+
+
+@dataclass(frozen=True, slots=True)
+class VariableResult:
+    """Server-side evaluation outcome for a single variable.
+
+    ``value`` is ``None`` whenever the platform served no value
+    (unknown key, targeting disabled, feature deleted/archived) —
+    callers using :meth:`Client.variable` directly should treat the
+    null case the same way :meth:`Client.variable_value` does (fall
+    back to a default). ``variation`` and ``feature`` are likewise
+    ``None`` in those cases.
+    """
+
+    key: str
+    value: Any
+    variation: str | None
+    reason: EvaluationReason
+    feature: str | None
+    evaluation_trace: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "VariableResult":
+        return cls(
+            key=payload["key"],
+            value=payload.get("value"),
+            variation=payload.get("variation"),
+            reason=payload.get("reason"),  # type: ignore[arg-type]
+            feature=payload.get("feature"),
+            evaluation_trace=payload.get("evaluation_trace"),
+        )
+
+
+@dataclass
+class EventPayload:
+    event: str
+    variable: str
+    variation: str
+    user: UserContext | None = None
+    value: float | None = None
+    occurred_at: str | None = None
+    evaluation_trace: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TrackEventsResult:
+    accepted: int
+
+
+class Client:
+    """HTTP client for the RedPennon variable-key evaluation API.
+
+    Two evaluation entry points cover the two ergonomics teams reach
+    for:
+
+      * :meth:`variable_value` — "give me the value or this fallback".
+        Swallows network and API errors and returns the caller's
+        default. This is the load-bearing contract: the developer's
+        default *always* wins on any failure, so the calling app
+        cannot crash because RedPennon is unreachable.
+
+      * :meth:`variable` — "give me the full result object" with
+        ``variation``, ``reason``, ``feature``, etc. Surfaces errors
+        as :class:`APIError`; opting in to the result shape opts in
+        to error handling.
+
+    Batch evaluation via :meth:`variables` lets one HTTP round-trip
+    resolve many flags against the same user context.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = 30.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._origin = base_url.rstrip("/")
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+
+    @property
+    def api_key(self) -> str:
+        return self._api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._origin
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Evaluation
+
+    def variable(
+        self,
+        key: str,
+        *,
+        user: UserContext | None = None,
+    ) -> VariableResult:
+        """Resolve one variable to its full :class:`VariableResult`."""
+        body: dict[str, Any] = {}
+        if user is not None:
+            body["user"] = user.to_payload()
+        response = self._post(
+            f"/v1/variables/{quote(key, safe='')}", body,
+        )
+        return VariableResult.from_payload(response.json())
+
+    def variable_value(
+        self,
+        key: str,
+        *,
+        default: T,
+        user: UserContext | None = None,
+    ) -> T:
+        """Resolve a variable and return its value, or ``default`` on
+        any failure (unreachable API, non-2xx, ``value=None``)."""
+        try:
+            result = self.variable(key, user=user)
+        except (APIError, httpx.HTTPError) as exc:
+            _LOG.warning("redpennon: variable_value(%r) failed: %s", key, exc)
+            return default
+        return default if result.value is None else result.value  # type: ignore[return-value]
+
+    def variables(
+        self,
+        keys: Iterable[str],
+        *,
+        user: UserContext | None = None,
+    ) -> dict[str, VariableResult]:
+        """Resolve a batch of variables in one HTTP round-trip."""
+        body: dict[str, Any] = {"keys": list(keys)}
+        if user is not None:
+            body["user"] = user.to_payload()
+        response = self._post("/v1/variables", body)
+        results = response.json().get("results", {})
+        return {k: VariableResult.from_payload(v) for k, v in results.items()}
+
+    def track_events(self, events: list[EventPayload]) -> TrackEventsResult:
+        """Record a batch of events against variable evaluations.
+
+        Raises :class:`APIError` on any non-202 response.
+        """
+        serialised = []
+        for ev in events:
+            item: dict[str, Any] = {
+                "event": ev.event,
+                "variable": ev.variable,
+                "variation": ev.variation,
+            }
+            if ev.user is not None:
+                item["user"] = ev.user.to_payload()
+            if ev.value is not None:
+                item["value"] = ev.value
+            if ev.occurred_at is not None:
+                item["occurred_at"] = ev.occurred_at
+            if ev.evaluation_trace is not None:
+                item["evaluation_trace"] = ev.evaluation_trace
+            serialised.append(item)
+        response = self._post("/v1/events", {"events": serialised})
+        return TrackEventsResult(accepted=response.json()["accepted"])
+
+    # ------------------------------------------------------------------
+    # Internal HTTP
+
+    def _post(self, path: str, body: Mapping[str, Any]) -> httpx.Response:
+        response = self._client.post(
+            f"{self._origin}{path}",
+            headers={
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+            },
+            json=body,
+        )
+        if response.status_code // 100 != 2:
+            message, code = self._error_fields(response)
+            raise APIError(response.status_code, message, code)
+        return response
+
+    @staticmethod
+    def _error_fields(response: httpx.Response) -> tuple[str, str | None]:
+        try:
+            payload = response.json()
+        except ValueError:
+            return (response.text or response.reason_phrase, None)
+        if not isinstance(payload, dict):
+            return (response.reason_phrase, None)
+        message = str(payload["error"]) if "error" in payload else response.reason_phrase
+        raw_code = payload.get("code")
+        code = str(raw_code) if isinstance(raw_code, str) and raw_code else None
+        return message, code

redpennon-1.0.0/tests/test_client.py

@@ -0,0 +1,442 @@
+"""Tests for the RedPennon Python client.
+
+We drive the client through an ``httpx.MockTransport`` so every test
+asserts on the exact HTTP request the SDK sends (URL, headers, body)
+and on the exact response the SDK surfaces. This is the only way to
+pin the SDK ↔ API contract without spinning up the full Django service
+under test.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from redpennon import APIError, Client, DEFAULT_API_BASE_URL, UserContext
+from redpennon.client import EventPayload, TrackEventsResult, VariableResult
+
+
+def _mock_transport(handler):
+    """Wrap a request handler in an ``httpx.MockTransport`` that
+    captures every outbound request and a list the test can assert on."""
+    captured: list[httpx.Request] = []
+
+    def _wrapped(request: httpx.Request) -> httpx.Response:
+        captured.append(request)
+        return handler(request)
+
+    return httpx.MockTransport(_wrapped), captured
+
+
+def _client_with(handler) -> tuple[Client, list[httpx.Request]]:
+    transport, captured = _mock_transport(handler)
+    http = httpx.Client(transport=transport)
+    return Client(api_key="env-key", client=http), captured
+
+
+# ----------------------------------------------------------------------
+# Construction + plumbing
+#
+# Construction (api key, injected httpx.Client, default base URL) is
+# exercised transitively by every per-method test below via
+# ``_client_with``; redundant smoke tests were removed to keep this file
+# focused on contract behaviour.
+
+def test_api_error_exposes_status_code_and_message() -> None:
+    err = APIError(401, "Invalid or missing API key.")
+    assert err.status_code == 401
+    assert err.message == "Invalid or missing API key."
+    assert err.code is None
+    assert "401" in str(err)
+
+
+def test_api_error_parses_governance_code_from_response_body() -> None:
+    """Governance error responses carry ``{"error", "code"}``; callers
+    branch on ``code`` (``rate_limit_exceeded``, ``organisation_suspended``
+    …) rather than parsing ``message``. The code propagates through
+    ``Client._post`` whenever the body is structured JSON."""
+    import httpx
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429,
+            json={"error": "Rate limit exceeded.", "code": "rate_limit_exceeded"},
+        )
+
+    client, _ = _client_with(handler)
+    with client, pytest.raises(APIError) as exc:
+        client.variable("any-key")
+
+    assert exc.value.status_code == 429
+    assert exc.value.code == "rate_limit_exceeded"
+
+
+def test_user_context_omits_unset_optional_fields() -> None:
+    assert UserContext(id="u1").to_payload() == {"id": "u1"}
+
+
+def test_user_context_serialises_builtins_and_custom_data() -> None:
+    payload = UserContext(
+        id="u1",
+        email="a@b.com",
+        organisation_id="o1",
+        ip="1.2.3.4",
+        audiences=["beta"],
+        app_version="4.12.0",
+        platform="ios",
+        country="AU",
+        custom_data={"plan": "enterprise", "trial_days": 7},
+    ).to_payload()
+    assert payload == {
+        "id": "u1",
+        "email": "a@b.com",
+        "organisation_id": "o1",
+        "ip": "1.2.3.4",
+        "audiences": ["beta"],
+        "app_version": "4.12.0",
+        "platform": "ios",
+        "country": "AU",
+        "custom_data": {"plan": "enterprise", "trial_days": 7},
+    }
+
+
+# ----------------------------------------------------------------------
+# ``variable()`` — single-key, full result
+
+class TestVariable:
+    def test_returns_full_result_shape(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "key": "show-banner",
+                "value": True,
+                "variation": "on",
+                "reason": "targeting_rule_matched",
+                "feature": "marketing",
+            })
+
+        client, captured = _client_with(handler)
+        with client:
+            result = client.variable("show-banner", user=UserContext(id="u"))
+
+        assert isinstance(result, VariableResult)
+        assert result.key == "show-banner"
+        assert result.value is True
+        assert result.variation == "on"
+        assert result.reason == "targeting_rule_matched"
+        assert result.feature == "marketing"
+
+        assert len(captured) == 1
+        req = captured[0]
+        assert str(req.url) == f"{DEFAULT_API_BASE_URL}/v1/variables/show-banner"
+        assert req.method == "POST"
+        assert req.headers["X-API-Key"] == "env-key"
+        assert req.headers["Content-Type"] == "application/json"
+        assert json.loads(req.content) == {"user": {"id": "u"}}
+
+    def test_url_encodes_the_key(self) -> None:
+        captured_urls: list[str] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured_urls.append(str(req.url))
+            return httpx.Response(200, json={
+                "key": "weird/key", "value": None, "variation": None,
+                "reason": "variable_not_found", "feature": None,
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            client.variable("weird/key")
+
+        assert captured_urls[0].endswith("/v1/variables/weird%2Fkey")
+
+    def test_omits_user_when_no_context_supplied(self) -> None:
+        captured_bodies: list[bytes] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured_bodies.append(req.content)
+            return httpx.Response(200, json={
+                "key": "k", "value": False, "variation": "off",
+                "reason": "default_variation", "feature": "f",
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            client.variable("k")
+
+        assert json.loads(captured_bodies[0]) == {}
+
+    def test_non_2xx_raises_api_error(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"error": "Invalid or missing API key."})
+
+        client, _ = _client_with(handler)
+        with client, pytest.raises(APIError) as exc:
+            client.variable("k")
+
+        assert exc.value.status_code == 401
+
+    def test_populates_evaluation_trace_when_present(self) -> None:
+        """evaluation_trace is an opaque signed string, not a dict."""
+        trace = "rpe_v1:sometoken"
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "key": "show-banner",
+                "value": True,
+                "variation": "on",
+                "reason": "targeting_rule_matched",
+                "feature": "marketing",
+                "evaluation_trace": trace,
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            result = client.variable("show-banner")
+
+        assert isinstance(result.evaluation_trace, str)
+        assert result.evaluation_trace == "rpe_v1:sometoken"
+
+    def test_evaluation_trace_is_none_when_absent(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "key": "k", "value": False, "variation": "off",
+                "reason": "default_variation", "feature": "f",
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            result = client.variable("k")
+
+        assert result.evaluation_trace is None
+
+
+# ----------------------------------------------------------------------
+# ``variable_value()`` — fail-open fallback to caller's default
+
+class TestVariableValue:
+    def test_returns_server_value(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "key": "discount-pct", "value": 25, "variation": "on",
+                "reason": "targeting_rule_matched", "feature": "promo",
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            value = client.variable_value("discount-pct", default=0, user=UserContext(id="u"))
+        assert value == 25
+
+    def test_falls_back_when_value_is_null(self) -> None:
+        """``variable_not_found``, deleted/archived features, and
+        targeting-disabled all surface as ``value=None``; the SDK
+        substitutes the caller's default."""
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "key": "discount-pct", "value": None, "variation": None,
+                "reason": "variable_not_found", "feature": None,
+            })
+
+        client, _ = _client_with(handler)
+        with client:
+            value = client.variable_value("discount-pct", default=10)
+        assert value == 10
+
+    def test_swallows_network_errors_and_returns_default(self) -> None:
+        """An unreachable API must not crash the caller. The
+        result-shape ``variable()`` method still raises — callers that
+        want errors can opt in to it."""
+        def handler(req: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("offline")
+
+        client, _ = _client_with(handler)
+        with client:
+            value = client.variable_value("flag", default="fallback")
+        assert value == "fallback"
+
+    def test_swallows_api_errors_and_returns_default(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"error": "nope"})
+
+        client, _ = _client_with(handler)
+        with client:
+            value = client.variable_value("flag", default=False)
+        assert value is False
+
+
+# ----------------------------------------------------------------------
+# ``variables()`` — batch
+
+class TestVariablesBatch:
+    def test_returns_result_per_key(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={
+                "results": {
+                    "a": {
+                        "key": "a", "value": True, "variation": "on",
+                        "reason": "default_variation", "feature": "f-a",
+                    },
+                    "b": {
+                        "key": "b", "value": None, "variation": None,
+                        "reason": "variable_not_found", "feature": None,
+                    },
+                },
+            })
+
+        client, captured = _client_with(handler)
+        with client:
+            results = client.variables(["a", "b"], user=UserContext(id="u"))
+
+        assert results["a"].value is True
+        assert results["b"].reason == "variable_not_found"
+        assert str(captured[0].url) == f"{DEFAULT_API_BASE_URL}/v1/variables"
+        assert json.loads(captured[0].content) == {
+            "keys": ["a", "b"],
+            "user": {"id": "u"},
+        }
+
+    def test_omits_user_when_no_context_supplied(self) -> None:
+        captured_bodies: list[bytes] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured_bodies.append(req.content)
+            return httpx.Response(200, json={"results": {}})
+
+        client, _ = _client_with(handler)
+        with client:
+            client.variables([])
+
+        assert json.loads(captured_bodies[0]) == {"keys": []}
+
+    def test_non_2xx_raises_api_error(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"error": "nope"})
+
+        client, _ = _client_with(handler)
+        with client, pytest.raises(APIError) as exc:
+            client.variables(["x"])
+
+        assert exc.value.status_code == 401
+
+
+# ----------------------------------------------------------------------
+# ``track_events()`` — POST /v1/events
+
+class TestTrackEvents:
+    def test_returns_accepted_count(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(202, json={"accepted": 2})
+
+        client, captured = _client_with(handler)
+        events = [
+            EventPayload(event="button_clicked", variable="checkout-flow", variation="variant-a"),
+            EventPayload(event="page_viewed", variable="new-nav", variation="on"),
+        ]
+        with client:
+            result = client.track_events(events)
+
+        assert isinstance(result, TrackEventsResult)
+        assert result.accepted == 2
+
+        req = captured[0]
+        assert str(req.url) == f"{DEFAULT_API_BASE_URL}/v1/events"
+        assert req.method == "POST"
+        assert req.headers["X-API-Key"] == "env-key"
+        assert req.headers["Content-Type"] == "application/json"
+        body = json.loads(req.content)
+        assert body == {
+            "events": [
+                {"event": "button_clicked", "variable": "checkout-flow", "variation": "variant-a"},
+                {"event": "page_viewed", "variable": "new-nav", "variation": "on"},
+            ]
+        }
+
+    def test_serialises_all_optional_fields(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(202, json={"accepted": 1})
+
+        client, captured = _client_with(handler)
+        event = EventPayload(
+            event="purchase",
+            variable="checkout-flow",
+            variation="variant-a",
+            user=UserContext(id="user-123"),
+            value=42.5,
+            occurred_at="2026-05-01T05:06:07Z",
+            evaluation_trace="rpe_v1:abc123",
+        )
+        with client:
+            client.track_events([event])
+
+        body = json.loads(captured[0].content)
+        assert body["events"][0] == {
+            "event": "purchase",
+            "variable": "checkout-flow",
+            "variation": "variant-a",
+            "user": {"id": "user-123"},
+            "value": 42.5,
+            "occurred_at": "2026-05-01T05:06:07Z",
+            "evaluation_trace": "rpe_v1:abc123",
+        }
+
+    def test_omits_none_optional_fields(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(202, json={"accepted": 1})
+
+        client, captured = _client_with(handler)
+        with client:
+            client.track_events([
+                EventPayload(event="e", variable="v", variation="var")
+            ])
+
+        body = json.loads(captured[0].content)
+        event_body = body["events"][0]
+        assert "user" not in event_body
+        assert "value" not in event_body
+        assert "occurred_at" not in event_body
+        assert "evaluation_trace" not in event_body
+
+    def test_non_202_raises_api_error(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"error": "Invalid or missing API key."})
+
+        client, _ = _client_with(handler)
+        with client, pytest.raises(APIError) as exc:
+            client.track_events([
+                EventPayload(event="e", variable="v", variation="var")
+            ])
+
+        assert exc.value.status_code == 401
+
+    def test_raises_api_error_with_governance_code(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                429,
+                json={"error": "Rate limit exceeded.", "code": "rate_limit_exceeded"},
+            )
+
+        client, _ = _client_with(handler)
+        with client, pytest.raises(APIError) as exc:
+            client.track_events([
+                EventPayload(event="e", variable="v", variation="var")
+            ])
+
+        assert exc.value.status_code == 429
+        assert exc.value.code == "rate_limit_exceeded"
+
+    def test_raises_api_error_on_events_batch_too_large(self) -> None:
+        def handler(req: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                413,
+                json={"error": "Batch too large.", "code": "events_batch_too_large"},
+            )
+
+        client, _ = _client_with(handler)
+        with client, pytest.raises(APIError) as exc:
+            client.track_events([
+                EventPayload(event="e", variable="v", variation="var")
+            ])
+
+        assert exc.value.status_code == 413
+        assert exc.value.code == "events_batch_too_large"