openfeature-provider-posthog 0.1.1__tar.gz

openfeature_provider_posthog-0.1.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 PostHog (part of Hiberly Inc)
+
+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.

openfeature_provider_posthog-0.1.1/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: openfeature-provider-posthog
+Version: 0.1.1
+Summary: Official PostHog provider for the OpenFeature Python SDK.
+Author-email: PostHog <engineering@posthog.com>
+Maintainer-email: PostHog <engineering@posthog.com>
+License: MIT
+Project-URL: Homepage, https://github.com/posthog/posthog-python
+Project-URL: Repository, https://github.com/posthog/posthog-python
+Project-URL: Documentation, https://posthog.com/docs/feature-flags/installation/openfeature
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: posthog<8.0.0,>=7.0.0
+Requires-Dist: openfeature-sdk>=0.8.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file

openfeature_provider_posthog-0.1.1/openfeature/contrib/provider/posthog/__init__.py

@@ -0,0 +1,3 @@
+from openfeature.contrib.provider.posthog.provider import PostHogProvider
+
+__all__ = ["PostHogProvider"]

openfeature_provider_posthog-0.1.1/openfeature/contrib/provider/posthog/provider.py

@@ -0,0 +1,285 @@
+"""Official PostHog provider for the OpenFeature Python SDK.
+
+This wraps a configured :class:`posthog.Posthog` client and exposes flag
+evaluation through OpenFeature's :class:`~openfeature.provider.AbstractProvider`
+contract, using the modern, single-call ``Client.get_feature_flag_result`` API.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Mapping, Optional, Sequence, TypeVar, Union
+
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.exception import (
+    FlagNotFoundError,
+    TargetingKeyMissingError,
+    TypeMismatchError,
+)
+from openfeature.flag_evaluation import FlagResolutionDetails, Reason
+from openfeature.provider import AbstractProvider
+from openfeature.provider.metadata import Metadata
+
+import posthog
+from posthog.types import FeatureFlagResult
+
+# Reserved evaluation-context attribute keys. Every other attribute in
+# ``evaluation_context.attributes`` is forwarded as a PostHog person property.
+GROUPS_KEY = "groups"
+GROUP_PROPERTIES_KEY = "group_properties"
+_RESERVED_KEYS = frozenset({GROUPS_KEY, GROUP_PROPERTIES_KEY})
+
+ObjectValue = Union[Sequence[Any], Mapping[str, Any]]
+
+_T = TypeVar("_T")
+_N = TypeVar("_N", int, float)
+
+_logger = logging.getLogger(__name__)
+
+
+class PostHogProvider(AbstractProvider):
+    """OpenFeature provider backed by a configured :class:`posthog.Posthog` client.
+
+    The caller owns the PostHog client lifecycle: construct and configure the
+    client yourself (project key, ``personal_api_key`` for local evaluation,
+    ``host``, ...), then hand it to this provider.
+
+    Evaluation-context mapping:
+        * ``targeting_key``               -> PostHog ``distinct_id``
+        * reserved attr ``groups``        -> PostHog ``groups``
+        * reserved attr ``group_properties`` -> PostHog ``group_properties``
+        * every other attribute           -> PostHog ``person_properties``
+
+    Flag-type mapping (all via ``get_feature_flag_result``):
+        * boolean -> ``enabled``
+        * string  -> the multivariate ``variant`` key
+        * int/float -> the ``variant`` parsed to a number
+        * object  -> the flag's JSON ``payload``
+
+    Args:
+        client: A configured :class:`posthog.Posthog` instance.
+        default_distinct_id: Distinct ID to use when the evaluation context has
+            no ``targeting_key``. If ``None`` (default), a missing targeting key
+            raises :class:`~openfeature.exception.TargetingKeyMissingError`,
+            which is OpenFeature-idiomatic. Set a value (e.g. ``"anonymous"``)
+            to opt into anonymous evaluation.
+        send_feature_flag_events: Forwarded to ``get_feature_flag_result`` to
+            control ``$feature_flag_called`` capture. Defaults to ``True`` so
+            PostHog flag analytics (and experiments) keep working.
+    """
+
+    def __init__(
+        self,
+        client: posthog.Posthog,
+        *,
+        default_distinct_id: Optional[str] = None,
+        send_feature_flag_events: bool = True,
+    ) -> None:
+        super().__init__()
+        self._client = client
+        self._default_distinct_id = default_distinct_id
+        self._send_feature_flag_events = send_feature_flag_events
+
+    # -- metadata / lifecycle -------------------------------------------------
+
+    def get_metadata(self) -> Metadata:
+        return Metadata(name="PostHogProvider")
+
+    def initialize(self, evaluation_context: EvaluationContext) -> None:
+        # Preload locally-evaluated flag definitions only when the injected
+        # client is configured for local evaluation. We do not otherwise mutate
+        # the caller-owned client, and a preload failure must not make the
+        # OpenFeature client un-ready (remote evaluation still works).
+        if getattr(self._client, "personal_api_key", None):
+            try:
+                self._client.load_feature_flags()
+            except Exception:
+                # Don't block the OpenFeature client on a preload failure
+                # (remote evaluation still works), but surface it: an invalid
+                # personal_api_key, unreachable host, or missing permissions
+                # would otherwise silently disable local evaluation.
+                _logger.warning(
+                    "PostHogProvider: failed to preload feature flag "
+                    "definitions for local evaluation; falling back to remote "
+                    "evaluation.",
+                    exc_info=True,
+                )
+
+    def shutdown(self) -> None:
+        # The provider does not own the injected client's lifecycle, so this is
+        # deliberately a no-op. Callers shut down their own ``Posthog`` client.
+        return None
+
+    # -- core resolution ------------------------------------------------------
+
+    def _resolve(
+        self,
+        flag_key: str,
+        evaluation_context: Optional[EvaluationContext],
+    ) -> FeatureFlagResult:
+        distinct_id = self._distinct_id(evaluation_context)
+        person_properties, groups, group_properties = self._split_context(
+            evaluation_context
+        )
+        result = self._client.get_feature_flag_result(
+            flag_key,
+            distinct_id,
+            groups=groups or None,
+            person_properties=person_properties or None,
+            group_properties=group_properties or None,
+            send_feature_flag_events=self._send_feature_flag_events,
+        )
+        if result is None:
+            raise FlagNotFoundError(f"Flag '{flag_key}' not found or disabled.")
+        return result
+
+    # -- typed resolvers ------------------------------------------------------
+
+    def resolve_boolean_details(
+        self,
+        flag_key: str,
+        default_value: bool,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[bool]:
+        result = self._resolve(flag_key, evaluation_context)
+        return self._details(result.enabled, result)
+
+    def resolve_string_details(
+        self,
+        flag_key: str,
+        default_value: str,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[str]:
+        result = self._resolve(flag_key, evaluation_context)
+        if result.variant is None:
+            if not result.enabled:
+                # The user matched no condition / the flag is off. This is not a
+                # type error: return the caller's default with a normal reason.
+                return self._details(default_value, result)
+            # Enabled but no variant => a boolean flag read as a string. Surface
+            # a type mismatch so the caller gets its default per the OF spec
+            # rather than a surprising "True"/"False".
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' has no string variant (boolean flag)."
+            )
+        return self._details(result.variant, result)
+
+    def resolve_integer_details(
+        self,
+        flag_key: str,
+        default_value: int,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[int]:
+        return self._resolve_number(flag_key, default_value, evaluation_context, int)
+
+    def resolve_float_details(
+        self,
+        flag_key: str,
+        default_value: float,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[float]:
+        return self._resolve_number(flag_key, default_value, evaluation_context, float)
+
+    def resolve_object_details(
+        self,
+        flag_key: str,
+        default_value: ObjectValue,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[ObjectValue]:
+        result = self._resolve(flag_key, evaluation_context)
+        payload = result.payload  # already JSON-deserialized by posthog
+        if not isinstance(payload, (dict, list)):
+            if not result.enabled:
+                # Non-enrolled / disabled flag: return the default with a normal
+                # reason rather than flagging it as a type error.
+                return self._details(default_value, result)
+            # Matched flag with no object payload => a genuine type mismatch.
+            raise TypeMismatchError(f"Flag '{flag_key}' has no object/JSON payload.")
+        return self._details(payload, result)
+
+    def _resolve_number(
+        self,
+        flag_key: str,
+        default_value: _N,
+        evaluation_context: Optional[EvaluationContext],
+        ctor: Callable[[str], _N],
+    ) -> FlagResolutionDetails[_N]:
+        result = self._resolve(flag_key, evaluation_context)
+        if result.variant is None:
+            if not result.enabled:
+                # Non-enrolled / disabled flag: not a type error.
+                return self._details(default_value, result)
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' has no variant to parse as {ctor.__name__}."
+            )
+        try:
+            value = ctor(result.variant)
+        except (TypeError, ValueError) as exc:
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' variant '{result.variant}' is not a valid "
+                f"{ctor.__name__}."
+            ) from exc
+        return self._details(value, result)
+
+    def _details(
+        self, value: _T, result: FeatureFlagResult
+    ) -> FlagResolutionDetails[_T]:
+        """Build resolution details with our shared reason/metadata wiring."""
+        return FlagResolutionDetails(
+            value=value,
+            variant=result.variant,
+            reason=self._map_reason(result),
+            flag_metadata=self._flag_metadata(result),
+        )
+
+    # -- helpers --------------------------------------------------------------
+
+    def _distinct_id(self, evaluation_context: Optional[EvaluationContext]) -> str:
+        if evaluation_context is not None and evaluation_context.targeting_key:
+            return evaluation_context.targeting_key
+        if self._default_distinct_id is not None:
+            return self._default_distinct_id
+        raise TargetingKeyMissingError(
+            "No targeting_key in evaluation context and no default_distinct_id "
+            "configured."
+        )
+
+    @staticmethod
+    def _split_context(
+        evaluation_context: Optional[EvaluationContext],
+    ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+        if evaluation_context is None or not evaluation_context.attributes:
+            return {}, {}, {}
+        attrs = evaluation_context.attributes
+        groups = attrs.get(GROUPS_KEY) or {}
+        group_properties = attrs.get(GROUP_PROPERTIES_KEY) or {}
+        person_properties = {k: v for k, v in attrs.items() if k not in _RESERVED_KEYS}
+        groups = groups if isinstance(groups, dict) else {}
+        group_properties = (
+            group_properties if isinstance(group_properties, dict) else {}
+        )
+        return person_properties, groups, group_properties
+
+    @staticmethod
+    def _map_reason(result: FeatureFlagResult) -> Reason:
+        """Map PostHog's free-text reason / enabled state to an OpenFeature Reason."""
+        if result.enabled:
+            # Enabled: the user matched a targeting condition (or was assigned a
+            # variant). PostHog has no distinct OpenFeature-style reason here.
+            return Reason.TARGETING_MATCH
+        # Not enabled. ``get_feature_flag_result`` returns ``None`` (surfaced as
+        # ``FlagNotFoundError`` one level up) for archived/non-existent flags, so
+        # a ``False`` result overwhelmingly means the flag is active but no
+        # targeting condition matched -> ``DEFAULT``. Only report ``DISABLED``
+        # (the flag itself is turned off) when the reason text says so.
+        text = (result.reason or "").lower()
+        if "disabled" in text:
+            return Reason.DISABLED
+        return Reason.DEFAULT
+
+    @staticmethod
+    def _flag_metadata(result: FeatureFlagResult) -> Mapping[str, Any]:
+        meta: dict[str, Any] = {}
+        if result.reason is not None:
+            meta["posthog_reason"] = result.reason
+        return meta

openfeature_provider_posthog-0.1.1/openfeature_provider_posthog.egg-info/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: openfeature-provider-posthog
+Version: 0.1.1
+Summary: Official PostHog provider for the OpenFeature Python SDK.
+Author-email: PostHog <engineering@posthog.com>
+Maintainer-email: PostHog <engineering@posthog.com>
+License: MIT
+Project-URL: Homepage, https://github.com/posthog/posthog-python
+Project-URL: Repository, https://github.com/posthog/posthog-python
+Project-URL: Documentation, https://posthog.com/docs/feature-flags/installation/openfeature
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: posthog<8.0.0,>=7.0.0
+Requires-Dist: openfeature-sdk>=0.8.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file

openfeature_provider_posthog-0.1.1/openfeature_provider_posthog.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+pyproject.toml
+openfeature/contrib/provider/posthog/__init__.py
+openfeature/contrib/provider/posthog/provider.py
+openfeature/contrib/provider/posthog/py.typed
+openfeature_provider_posthog.egg-info/PKG-INFO
+openfeature_provider_posthog.egg-info/SOURCES.txt
+openfeature_provider_posthog.egg-info/dependency_links.txt
+openfeature_provider_posthog.egg-info/requires.txt
+openfeature_provider_posthog.egg-info/top_level.txt
+tests/test_provider_e2e.py
+tests/test_provider_unit.py

openfeature_provider_posthog-0.1.1/openfeature_provider_posthog.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openfeature_provider_posthog-0.1.1/openfeature_provider_posthog.egg-info/requires.txt

@@ -0,0 +1,7 @@
+posthog<8.0.0,>=7.0.0
+openfeature-sdk>=0.8.0
+
+[dev]
+mypy
+ruff
+pytest

openfeature_provider_posthog-0.1.1/openfeature_provider_posthog.egg-info/top_level.txt

@@ -0,0 +1 @@
+openfeature

openfeature_provider_posthog-0.1.1/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openfeature-provider-posthog"
+version = "0.1.1"
+description = "Official PostHog provider for the OpenFeature Python SDK."
+authors = [{ name = "PostHog", email = "engineering@posthog.com" }]
+maintainers = [{ name = "PostHog", email = "engineering@posthog.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    # FeatureFlagResult / get_feature_flag_result are the modern, non-deprecated
+    # single-call API. Pinned to the posthog major this provider is released and
+    # tested against (both ship from this repo); bump the upper bound when moving
+    # the provider to a new posthog major.
+    "posthog>=7.0.0,<8.0.0",
+    "openfeature-sdk>=0.8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/posthog/posthog-python"
+Repository = "https://github.com/posthog/posthog-python"
+Documentation = "https://posthog.com/docs/feature-flags/installation/openfeature"
+
+[project.optional-dependencies]
+dev = [
+    "mypy",
+    "ruff",
+    "pytest",
+]
+
+[tool.setuptools]
+packages = ["openfeature.contrib.provider.posthog"]
+
+[tool.setuptools.package-data]
+"openfeature.contrib.provider.posthog" = ["py.typed"]
+
+# Local development: resolve posthog from the uv workspace (the repo root),
+# declared in the root pyproject's [tool.uv.workspace]. This guarantees the
+# provider is always built/tested against the in-repo posthog.
+[tool.uv.sources]
+posthog = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# This sub-project runs its own mypy (with openfeature-sdk installed in its env).
+[tool.mypy]
+python_version = "3.10"
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = "."
+ignore_missing_imports = true
+strict_optional = true
+check_untyped_defs = true

openfeature_provider_posthog-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openfeature_provider_posthog-0.1.1/tests/test_provider_e2e.py

@@ -0,0 +1,56 @@
+"""End-to-end tests through the OpenFeature public evaluation API."""
+
+from openfeature import api
+from openfeature.evaluation_context import EvaluationContext
+
+from openfeature.contrib.provider.posthog import PostHogProvider
+
+from tests.conftest import make_result
+
+
+def _register(fake_client):
+    api.set_provider(PostHogProvider(fake_client, default_distinct_id="anon"))
+    return api.get_client()
+
+
+def test_end_to_end_boolean_true(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(enabled=True)
+    client = _register(fake_client)
+    ctx = EvaluationContext(targeting_key="user-123")
+    assert client.get_boolean_value("flag", False, ctx) is True
+
+
+def test_end_to_end_string_variant(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="blue"
+    )
+    client = _register(fake_client)
+    ctx = EvaluationContext(targeting_key="user-123")
+    assert client.get_string_value("exp", "control", ctx) == "blue"
+
+
+def test_end_to_end_object_payload(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="v1", payload={"hex": "#00f"}
+    )
+    client = _register(fake_client)
+    ctx = EvaluationContext(targeting_key="user-123")
+    assert client.get_object_value("cfg", {}, ctx) == {"hex": "#00f"}
+
+
+def test_end_to_end_default_on_missing_flag(fake_client):
+    fake_client.get_feature_flag_result.return_value = None
+    client = _register(fake_client)
+    ctx = EvaluationContext(targeting_key="user-123")
+    # FlagNotFoundError inside the provider -> SDK returns the caller's default.
+    assert client.get_boolean_value("missing", True, ctx) is True
+
+
+def test_end_to_end_default_on_type_mismatch(fake_client):
+    # Boolean flag (no variant) read as a string -> TYPE_MISMATCH -> default.
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant=None
+    )
+    client = _register(fake_client)
+    ctx = EvaluationContext(targeting_key="user-123")
+    assert client.get_string_value("flag", "fallback", ctx) == "fallback"

openfeature_provider_posthog-0.1.1/tests/test_provider_unit.py

@@ -0,0 +1,250 @@
+import pytest
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.exception import (
+    FlagNotFoundError,
+    TargetingKeyMissingError,
+    TypeMismatchError,
+)
+from openfeature.flag_evaluation import Reason
+
+from openfeature.contrib.provider.posthog import PostHogProvider
+
+from tests.conftest import make_result
+
+
+def _provider(fake_client, **kwargs):
+    return PostHogProvider(fake_client, default_distinct_id="anon", **kwargs)
+
+
+def test_metadata(fake_client):
+    assert _provider(fake_client).get_metadata().name == "PostHogProvider"
+
+
+@pytest.mark.parametrize(
+    ("enabled", "reason", "expected_value", "expected_reason"),
+    [
+        (True, "matched condition set 1", True, Reason.TARGETING_MATCH),
+        # Active flag, user matched nothing -> DEFAULT (not DISABLED).
+        (False, "no condition set matched", False, Reason.DEFAULT),
+        # Only an explicitly-disabled flag maps to DISABLED.
+        (False, "flag is disabled", False, Reason.DISABLED),
+    ],
+)
+def test_boolean_reason_mapping(
+    fake_client, enabled, reason, expected_value, expected_reason
+):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=enabled, variant=None, reason=reason
+    )
+    details = _provider(fake_client).resolve_boolean_details(
+        "flag", not expected_value, EvaluationContext("user-1")
+    )
+    assert details.value is expected_value
+    assert details.reason == expected_reason
+    assert details.flag_metadata["posthog_reason"] == reason
+    fake_client.get_feature_flag_result.assert_called_once()
+
+
+def test_string_variant(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="control"
+    )
+    details = _provider(fake_client).resolve_string_details(
+        "exp", "x", EvaluationContext("user-1")
+    )
+    assert details.value == "control"
+    assert details.variant == "control"
+
+
+def test_string_on_boolean_flag_is_type_mismatch(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant=None
+    )
+    with pytest.raises(TypeMismatchError):
+        _provider(fake_client).resolve_string_details(
+            "flag", "x", EvaluationContext("user-1")
+        )
+
+
+@pytest.mark.parametrize(
+    ("resolver", "variant", "expected"),
+    [
+        ("resolve_integer_details", "42", 42),
+        ("resolve_integer_details", "3", 3),
+        ("resolve_float_details", "3.5", 3.5),
+        ("resolve_float_details", "3", 3.0),
+    ],
+)
+def test_number_variant_parse(fake_client, resolver, variant, expected):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant=variant
+    )
+    details = getattr(_provider(fake_client), resolver)("n", 0, EvaluationContext("u"))
+    assert details.value == expected
+
+
+@pytest.mark.parametrize(
+    ("resolver", "variant"),
+    [
+        ("resolve_integer_details", "not-an-int"),
+        ("resolve_integer_details", None),
+        ("resolve_float_details", "abc"),
+        ("resolve_float_details", None),
+    ],
+)
+def test_number_variant_parse_failure(fake_client, resolver, variant):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant=variant
+    )
+    with pytest.raises(TypeMismatchError):
+        getattr(_provider(fake_client), resolver)("n", 0, EvaluationContext("u"))
+
+
+def test_object_payload(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="v1", payload={"color": "blue"}
+    )
+    details = _provider(fake_client).resolve_object_details(
+        "cfg", {}, EvaluationContext("u")
+    )
+    assert details.value == {"color": "blue"}
+
+
+def test_object_payload_list(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="v1", payload=[1, 2, 3]
+    )
+    details = _provider(fake_client).resolve_object_details(
+        "cfg", {}, EvaluationContext("u")
+    )
+    assert details.value == [1, 2, 3]
+
+
+def test_object_missing_payload_is_type_mismatch(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=True, variant="v1", payload=None
+    )
+    with pytest.raises(TypeMismatchError):
+        _provider(fake_client).resolve_object_details("cfg", {}, EvaluationContext("u"))
+
+
+# A user who matches no condition / a disabled flag (enabled=False, variant/payload
+# absent) is NOT a type error: the default is returned with a normal reason and no
+# error_code, instead of TYPE_MISMATCH / Reason.ERROR.
+def test_string_unmatched_returns_default_without_error(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=False, variant=None, reason="no condition set matched"
+    )
+    details = _provider(fake_client).resolve_string_details(
+        "exp", "fallback", EvaluationContext("user-1")
+    )
+    assert details.value == "fallback"
+    assert details.reason == Reason.DEFAULT
+    assert details.error_code is None
+
+
+@pytest.mark.parametrize(
+    "resolver", ["resolve_integer_details", "resolve_float_details"]
+)
+def test_number_unmatched_returns_default_without_error(fake_client, resolver):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=False, variant=None, reason="no condition set matched"
+    )
+    details = getattr(_provider(fake_client), resolver)("n", 7, EvaluationContext("u"))
+    assert details.value == 7
+    assert details.reason == Reason.DEFAULT
+    assert details.error_code is None
+
+
+def test_object_unmatched_returns_default_without_error(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result(
+        enabled=False, variant=None, payload=None, reason="no condition set matched"
+    )
+    default = {"fallback": True}
+    details = _provider(fake_client).resolve_object_details(
+        "cfg", default, EvaluationContext("u")
+    )
+    assert details.value == default
+    assert details.reason == Reason.DEFAULT
+    assert details.error_code is None
+
+
+def test_flag_not_found_raises(fake_client):
+    fake_client.get_feature_flag_result.return_value = None
+    with pytest.raises(FlagNotFoundError):
+        _provider(fake_client).resolve_boolean_details(
+            "missing", False, EvaluationContext("u")
+        )
+
+
+def test_missing_targeting_key_no_default(fake_client):
+    provider = PostHogProvider(fake_client)  # no default_distinct_id
+    with pytest.raises(TargetingKeyMissingError):
+        provider.resolve_boolean_details("flag", False, EvaluationContext())
+
+
+def test_default_distinct_id_used_when_no_targeting_key(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result()
+    _provider(fake_client).resolve_boolean_details("flag", False, EvaluationContext())
+    args, _ = fake_client.get_feature_flag_result.call_args
+    assert args[1] == "anon"
+
+
+def test_context_split(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result()
+    ctx = EvaluationContext(
+        "u",
+        {
+            "plan": "pro",
+            "groups": {"org": "acme"},
+            "group_properties": {"org": {"tier": "ent"}},
+        },
+    )
+    _provider(fake_client).resolve_boolean_details("flag", False, ctx)
+    kwargs = fake_client.get_feature_flag_result.call_args.kwargs
+    assert kwargs["groups"] == {"org": "acme"}
+    assert kwargs["group_properties"] == {"org": {"tier": "ent"}}
+    assert kwargs["person_properties"] == {"plan": "pro"}
+
+
+@pytest.mark.parametrize("bad_value", ["acme", ["a", "b"], 42])
+def test_context_split_non_dict_groups_coerced_to_none(fake_client, bad_value):
+    # A non-dict `groups` / `group_properties` is coerced to {} and forwarded as
+    # None, never passed straight through to get_feature_flag_result.
+    fake_client.get_feature_flag_result.return_value = make_result()
+    ctx = EvaluationContext("u", {"groups": bad_value, "group_properties": bad_value})
+    _provider(fake_client).resolve_boolean_details("flag", False, ctx)
+    kwargs = fake_client.get_feature_flag_result.call_args.kwargs
+    assert kwargs["groups"] is None
+    assert kwargs["group_properties"] is None
+
+
+def test_send_feature_flag_events_forwarded(fake_client):
+    fake_client.get_feature_flag_result.return_value = make_result()
+    _provider(fake_client, send_feature_flag_events=False).resolve_boolean_details(
+        "flag", False, EvaluationContext("u")
+    )
+    assert (
+        fake_client.get_feature_flag_result.call_args.kwargs["send_feature_flag_events"]
+        is False
+    )
+
+
+def test_initialize_skips_preload_without_personal_api_key(fake_client):
+    # fake_client.personal_api_key is None by default.
+    PostHogProvider(fake_client).initialize(EvaluationContext())
+    fake_client.load_feature_flags.assert_not_called()
+
+
+def test_initialize_logs_warning_on_preload_failure(fake_client, caplog):
+    fake_client.personal_api_key = "phx_test"
+    fake_client.load_feature_flags.side_effect = RuntimeError("bad key")
+    with caplog.at_level("WARNING"):
+        PostHogProvider(fake_client).initialize(EvaluationContext())
+    fake_client.load_feature_flags.assert_called_once()
+    assert "failed to preload" in caplog.text
+
+
+def test_shutdown_does_not_touch_client(fake_client):
+    PostHogProvider(fake_client).shutdown()
+    fake_client.shutdown.assert_not_called()