mbuzz 0.7.0__tar.gz → 0.7.3__tar.gz

mbuzz-0.7.3/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.7.3 (2026-02-03)
+
+### Added
+
+- **Navigation-aware session creation** — middleware now only creates server-side sessions for real page navigations, filtering out Turbo frames, htmx partials, fetch/XHR, prefetch, and other sub-requests. Uses browser-enforced `Sec-Fetch-*` headers as the primary signal with a framework-specific blacklist fallback for old browsers.
+- `device_fingerprint()` utility — computes `SHA256(ip|user_agent)[0:32]`, matching the server-side fingerprint for session deduplication.
+- Async session creation via `POST /sessions` — fire-and-forget background thread on real navigations.
+
+### Fixed
+
+- **5x visit count inflation** caused by concurrent sub-requests (Turbo frames, htmx) each creating separate sessions on first page load.
+
+## 0.7.0 (2026-01-15)
+
+- Initial release with Flask middleware, visitor cookie management, event tracking, user identification, and conversion tracking.
+- Session cookie removed — server handles session resolution via device fingerprint.

{mbuzz-0.7.0 → mbuzz-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mbuzz
-Version: 0.7.0
+Version: 0.7.3
 Summary: Multi-touch attribution SDK for Python
 Project-URL: Homepage, https://mbuzz.co
 Project-URL: Documentation, https://mbuzz.co/docs/getting-started

{mbuzz-0.7.0 → mbuzz-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mbuzz"
-version = "0.7.0"
+version = "0.7.3"
 description = "Multi-touch attribution SDK for Python"
 readme = "README.md"
 license = "MIT"

{mbuzz-0.7.0 → mbuzz-0.7.3}/src/mbuzz/__init__.py

@@ -9,7 +9,7 @@ from .client.track import track, TrackResult
 from .client.identify import identify
 from .client.conversion import conversion, ConversionResult
 
-__version__ = "0.7.0"
+__version__ = "0.7.3"
 
 
 def init(

{mbuzz-0.7.0 → mbuzz-0.7.3}/src/mbuzz/api.py

@@ -10,7 +10,7 @@ from .config import config
 
 logger = logging.getLogger("mbuzz")
 
-VERSION = "0.1.0"
+VERSION = "0.7.3"
 
 
 def post(path: str, payload: Dict[str, Any]) -> bool:

{mbuzz-0.7.0 → mbuzz-0.7.3}/src/mbuzz/middleware/flask.py

@@ -1,14 +1,46 @@
 """Flask middleware for mbuzz tracking."""
 # NOTE: Session cookie removed in 0.7.0 - server handles session resolution
 
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
 from flask import Flask, request, g, Response
 
+from ..api import post
 from ..config import config
 from ..context import RequestContext, set_context, clear_context
 from ..cookies import VISITOR_COOKIE, VISITOR_MAX_AGE
+from ..utils.fingerprint import device_fingerprint
 from ..utils.identifier import generate_id
 
 
+def should_create_session() -> bool:
+    """Determine whether this request is a real page navigation.
+
+    Primary signal: Sec-Fetch-* headers (modern browsers, unforgeable).
+    Fallback: blacklist known sub-request framework headers (old browsers/bots).
+    """
+    mode = request.headers.get("Sec-Fetch-Mode")
+    dest = request.headers.get("Sec-Fetch-Dest")
+
+    if mode:
+        return (
+            mode == "navigate"
+            and dest == "document"
+            and not request.headers.get("Sec-Purpose")
+        )
+
+    # Fallback for old browsers / bots: blacklist known sub-requests
+    return (
+        not request.headers.get("Turbo-Frame")
+        and not request.headers.get("HX-Request")
+        and not request.headers.get("X-Up-Version")
+        and request.headers.get("X-Requested-With") != "XMLHttpRequest"
+    )
+
+
 def init_app(app: Flask) -> None:
     """Initialize mbuzz tracking for Flask app."""
 
@@ -24,6 +56,11 @@ def init_app(app: Flask) -> None:
         _set_request_context(visitor_id, ip, user_agent)
         _store_in_g(visitor_id)
 
+        if should_create_session():
+            _create_session_async(
+                visitor_id, request.url, request.referrer, ip, user_agent
+            )
+
     @app.after_request
     def after_request(response: Response) -> Response:
         if not hasattr(g, "mbuzz_visitor_id"):
@@ -83,6 +120,34 @@ def _store_in_g(visitor_id: str) -> None:
     g.mbuzz_is_new_visitor = VISITOR_COOKIE not in request.cookies
 
 
+def _create_session_async(
+    visitor_id: str,
+    url: str,
+    referrer: Optional[str],
+    ip: str,
+    user_agent: str,
+) -> None:
+    """Fire-and-forget session creation via background thread.
+
+    All data is captured before the thread starts — no request-object
+    access inside the thread (it would be invalid after the response).
+    """
+    payload = {
+        "session": {
+            "visitor_id": visitor_id,
+            "session_id": str(uuid.uuid4()),
+            "url": url,
+            "referrer": referrer,
+            "device_fingerprint": device_fingerprint(ip, user_agent),
+            "started_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+    }
+
+    threading.Thread(
+        target=post, args=("/sessions", payload), daemon=True
+    ).start()
+
+
 def _set_cookies(response: Response) -> None:
     """Set visitor cookie on response."""
     secure = request.is_secure

mbuzz-0.7.3/src/mbuzz/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Utility functions for mbuzz SDK."""
+
+from .identifier import generate_id
+from .fingerprint import device_fingerprint
+
+__all__ = ["generate_id", "device_fingerprint"]

mbuzz-0.7.3/src/mbuzz/utils/fingerprint.py

@@ -0,0 +1,12 @@
+"""Device fingerprint generation — matches server-side SHA256(ip|user_agent)[0:32]."""
+
+import hashlib
+
+
+def device_fingerprint(ip: str, user_agent: str) -> str:
+    """Compute a device fingerprint from IP and User-Agent.
+
+    Produces a 32-char hex string identical to the server-side computation
+    and the Ruby/Node SDKs.
+    """
+    return hashlib.sha256(f"{ip}|{user_agent}".encode()).hexdigest()[:32]

{mbuzz-0.7.0 → mbuzz-0.7.3}/tests/test_client.py

@@ -411,3 +411,43 @@ class TestConversion:
         call_args = mock_post.call_args[0]
         payload = call_args[1]
         assert payload["identifier"] == {"email": "test@example.com"}
+
+    @patch("mbuzz.client.conversion.post_with_response")
+    def test_uses_context_ip_and_user_agent(self, mock_post):
+        """Should use ip and user_agent from context if not explicitly provided."""
+        mock_post.return_value = {"conversion": {"id": "conv_123"}}
+        set_context(RequestContext(
+            visitor_id="ctx_vid",
+            ip="203.0.113.50",
+            user_agent="Safari/17.0",
+        ))
+
+        result = conversion(conversion_type="purchase")
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["ip"] == "203.0.113.50"
+        assert payload["user_agent"] == "Safari/17.0"
+
+    @patch("mbuzz.client.conversion.post_with_response")
+    def test_explicit_ip_overrides_context(self, mock_post):
+        """Should use explicit ip/user_agent over context."""
+        mock_post.return_value = {"conversion": {"id": "conv_123"}}
+        set_context(RequestContext(
+            visitor_id="ctx_vid",
+            ip="context_ip",
+            user_agent="context_ua",
+        ))
+
+        result = conversion(
+            conversion_type="purchase",
+            ip="explicit_ip",
+            user_agent="explicit_ua"
+        )
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["ip"] == "explicit_ip"
+        assert payload["user_agent"] == "explicit_ua"

mbuzz-0.7.3/tests/test_fingerprint.py

@@ -0,0 +1,33 @@
+"""Tests for device fingerprint utility."""
+
+from mbuzz.utils.fingerprint import device_fingerprint
+
+
+class TestDeviceFingerprint:
+    """Test device_fingerprint matches server-side SHA256(ip|user_agent)[0:32]."""
+
+    def test_ruby_parity(self):
+        """Must produce identical output to Ruby: Digest::SHA256.hexdigest('127.0.0.1|Mozilla/5.0')[0,32]."""
+        result = device_fingerprint("127.0.0.1", "Mozilla/5.0")
+        assert result == "ea687534a507e203bdef87cee3cc60c5"
+
+    def test_deterministic(self):
+        """Same input must always produce same output."""
+        a = device_fingerprint("10.0.0.1", "TestAgent/1.0")
+        b = device_fingerprint("10.0.0.1", "TestAgent/1.0")
+        assert a == b
+
+    def test_unique_for_different_inputs(self):
+        """Different inputs must produce different outputs."""
+        a = device_fingerprint("10.0.0.1", "Agent-A")
+        b = device_fingerprint("10.0.0.2", "Agent-A")
+        c = device_fingerprint("10.0.0.1", "Agent-B")
+        assert a != b
+        assert a != c
+        assert b != c
+
+    def test_returns_32_char_hex(self):
+        """Must return exactly 32 lowercase hex characters."""
+        result = device_fingerprint("192.168.1.1", "Chrome/120")
+        assert len(result) == 32
+        assert all(c in "0123456789abcdef" for c in result)

{mbuzz-0.7.0 → mbuzz-0.7.3}/tests/test_middleware.py

@@ -4,7 +4,7 @@ import pytest
 from unittest.mock import patch, MagicMock
 from flask import Flask, g
 
-from mbuzz.middleware.flask import init_app
+from mbuzz.middleware.flask import init_app, should_create_session
 from mbuzz.config import config
 from mbuzz.context import get_context, clear_context
 from mbuzz.cookies import VISITOR_COOKIE, VISITOR_MAX_AGE
@@ -342,3 +342,207 @@ class TestFlaskMiddleware:
             assert response.status_code == 500
             # Context should still be cleared
             assert get_context() is None
+
+
+class TestNavigationDetection:
+    """Test should_create_session() — Sec-Fetch-* whitelist + framework blacklist fallback.
+
+    Mirrors the e2e test at sdk_integration_tests/scenarios/navigation_detection_test.rb.
+    """
+
+    def setup_method(self):
+        config.reset()
+        clear_context()
+        self.app = Flask(__name__)
+        self.app.config["TESTING"] = True
+
+        @self.app.route("/")
+        def index():
+            return "OK"
+
+    def teardown_method(self):
+        config.reset()
+        clear_context()
+
+    # -----------------------------------------------------------------
+    # Whitelist path: modern browsers with Sec-Fetch-* headers
+    # -----------------------------------------------------------------
+
+    def test_real_navigation_returns_true(self):
+        """navigate + document = real page navigation → create session."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Dest": "document",
+            }
+        ):
+            assert should_create_session() is True
+
+    def test_turbo_frame_returns_false(self):
+        """same-origin + empty + Turbo-Frame → sub-request → skip."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "same-origin",
+                "Sec-Fetch-Dest": "empty",
+                "Turbo-Frame": "content_frame",
+            }
+        ):
+            assert should_create_session() is False
+
+    def test_htmx_returns_false(self):
+        """same-origin + empty + HX-Request → sub-request → skip."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "same-origin",
+                "Sec-Fetch-Dest": "empty",
+                "HX-Request": "true",
+            }
+        ):
+            assert should_create_session() is False
+
+    def test_fetch_xhr_returns_false(self):
+        """cors + empty → fetch/XHR → skip."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "cors",
+                "Sec-Fetch-Dest": "empty",
+            }
+        ):
+            assert should_create_session() is False
+
+    def test_prefetch_returns_false(self):
+        """navigate + document + Sec-Purpose: prefetch → skip."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Dest": "document",
+                "Sec-Purpose": "prefetch",
+            }
+        ):
+            assert should_create_session() is False
+
+    def test_iframe_returns_false(self):
+        """navigate + iframe → not a document navigation → skip."""
+        with self.app.test_request_context(
+            "/", headers={
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Dest": "iframe",
+            }
+        ):
+            assert should_create_session() is False
+
+    # -----------------------------------------------------------------
+    # Blacklist fallback: old browsers without Sec-Fetch-* headers
+    # -----------------------------------------------------------------
+
+    def test_old_browser_no_framework_headers_returns_true(self):
+        """No Sec-Fetch, no framework headers → allow (legacy browser)."""
+        with self.app.test_request_context("/"):
+            assert should_create_session() is True
+
+    def test_old_browser_turbo_frame_returns_false(self):
+        """No Sec-Fetch + Turbo-Frame → blacklist catches it."""
+        with self.app.test_request_context(
+            "/", headers={"Turbo-Frame": "lazy_banner"}
+        ):
+            assert should_create_session() is False
+
+    def test_old_browser_hx_request_returns_false(self):
+        """No Sec-Fetch + HX-Request → blacklist catches it."""
+        with self.app.test_request_context(
+            "/", headers={"HX-Request": "true"}
+        ):
+            assert should_create_session() is False
+
+    def test_old_browser_xhr_returns_false(self):
+        """No Sec-Fetch + X-Requested-With: XMLHttpRequest → blacklist catches it."""
+        with self.app.test_request_context(
+            "/", headers={"X-Requested-With": "XMLHttpRequest"}
+        ):
+            assert should_create_session() is False
+
+    def test_old_browser_unpoly_returns_false(self):
+        """No Sec-Fetch + X-Up-Version → blacklist catches it."""
+        with self.app.test_request_context(
+            "/", headers={"X-Up-Version": "3.0.0"}
+        ):
+            assert should_create_session() is False
+
+    # -----------------------------------------------------------------
+    # Middleware integration: session creation + cookie behavior
+    # -----------------------------------------------------------------
+
+    @patch("mbuzz.middleware.flask.post")
+    def test_navigation_calls_post_sessions(self, mock_post):
+        """Real navigation must fire POST /sessions."""
+        config.init(api_key="sk_test_123")
+        init_app(self.app)
+
+        with self.app.test_client() as client:
+            client.get("/", headers={
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Dest": "document",
+            })
+
+        mock_post.assert_called_once()
+        args = mock_post.call_args
+        assert args[0][0] == "/sessions"
+        payload = args[0][1]
+        assert "session" in payload
+        assert "visitor_id" in payload["session"]
+        assert "session_id" in payload["session"]
+        assert "device_fingerprint" in payload["session"]
+        assert len(payload["session"]["device_fingerprint"]) == 32
+
+    @patch("mbuzz.middleware.flask.post")
+    def test_turbo_frame_does_not_call_post(self, mock_post):
+        """Turbo frame request must NOT fire POST /sessions."""
+        config.init(api_key="sk_test_123")
+        init_app(self.app)
+
+        with self.app.test_client() as client:
+            client.get("/", headers={
+                "Sec-Fetch-Mode": "same-origin",
+                "Sec-Fetch-Dest": "empty",
+                "Turbo-Frame": "banner",
+            })
+
+        mock_post.assert_not_called()
+
+    @patch("mbuzz.middleware.flask.post")
+    def test_visitor_cookie_set_on_sub_request(self, mock_post):
+        """Visitor cookie must be set even when session creation is skipped."""
+        config.init(api_key="sk_test_123")
+        init_app(self.app)
+
+        with self.app.test_client() as client:
+            response = client.get("/", headers={
+                "Sec-Fetch-Mode": "same-origin",
+                "Sec-Fetch-Dest": "empty",
+                "Turbo-Frame": "banner",
+            })
+
+            cookies = response.headers.getlist("Set-Cookie")
+            visitor_cookie = next(
+                (c for c in cookies if VISITOR_COOKIE in c), None
+            )
+            assert visitor_cookie is not None
+
+    @patch("mbuzz.middleware.flask.post")
+    def test_response_always_succeeds(self, mock_post):
+        """Request completes normally regardless of navigation detection outcome."""
+        config.init(api_key="sk_test_123")
+        init_app(self.app)
+
+        with self.app.test_client() as client:
+            nav = client.get("/", headers={
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Dest": "document",
+            })
+            sub = client.get("/", headers={
+                "Sec-Fetch-Mode": "same-origin",
+                "Sec-Fetch-Dest": "empty",
+            })
+
+            assert nav.status_code == 200
+            assert sub.status_code == 200