mbuzz 0.2.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.2.0 → mbuzz-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mbuzz
-Version: 0.2.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.2.0 → mbuzz-0.7.3}/pyproject.toml

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

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

@@ -1,4 +1,5 @@
 """Mbuzz - Multi-touch attribution SDK for Python."""
+# NOTE: Session ID removed in 0.7.0 - server handles session resolution
 
 from typing import Any, Dict, Optional, Union
 
@@ -8,7 +9,7 @@ from .client.track import track, TrackResult
 from .client.identify import identify
 from .client.conversion import conversion, ConversionResult
 
-__version__ = "0.2.0"
+__version__ = "0.7.3"
 
 
 def init(
@@ -61,12 +62,6 @@ def visitor_id() -> Optional[str]:
     return ctx.visitor_id if ctx else None
 
 
-def session_id() -> Optional[str]:
-    """Get current session ID from context."""
-    ctx = get_context()
-    return ctx.session_id if ctx else None
-
-
 def user_id() -> Optional[str]:
     """Get current user ID from context."""
     ctx = get_context()
@@ -79,7 +74,6 @@ __all__ = [
     "conversion",
     "identify",
     "visitor_id",
-    "session_id",
     "user_id",
     "TrackResult",
     "ConversionResult",

{mbuzz-0.2.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.2.0 → mbuzz-0.7.3}/src/mbuzz/client/conversion.py

@@ -1,4 +1,5 @@
 """Conversion request for tracking conversions."""
+# NOTE: Session ID removed in 0.7.0 - server handles session resolution
 
 from dataclasses import dataclass
 from typing import Any, Dict, Optional, Union
@@ -26,6 +27,9 @@ def conversion(
     is_acquisition: bool = False,
     inherit_acquisition: bool = False,
     properties: Optional[Dict[str, Any]] = None,
+    ip: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    identifier: Optional[Dict[str, str]] = None,
 ) -> ConversionResult:
     """Track a conversion.
 
@@ -39,6 +43,9 @@ def conversion(
         is_acquisition: Whether this is a customer acquisition
         inherit_acquisition: Whether to inherit acquisition from previous conversion
         properties: Additional conversion properties
+        ip: Client IP address for server-side session resolution
+        user_agent: Client user agent for server-side session resolution
+        identifier: Cross-device identifier (email, user_id, etc.)
 
     Returns:
         ConversionResult with success status, conversion ID, and attribution data
@@ -47,22 +54,36 @@ def conversion(
 
     visitor_id = visitor_id or (ctx.visitor_id if ctx else None)
     user_id = user_id or (ctx.user_id if ctx else None)
+    ip = ip or (ctx.ip if ctx else None)
+    user_agent = user_agent or (ctx.user_agent if ctx else None)
 
     if not visitor_id and not user_id:
         return ConversionResult(success=False)
 
-    payload = {
+    payload: Dict[str, Any] = {
         "conversion_type": conversion_type,
-        "visitor_id": visitor_id,
-        "user_id": str(user_id) if user_id else None,
-        "event_id": event_id,
-        "revenue": revenue,
         "currency": currency,
         "is_acquisition": is_acquisition,
         "inherit_acquisition": inherit_acquisition,
         "properties": properties or {},
     }
 
+    # Only include non-None values
+    if visitor_id:
+        payload["visitor_id"] = visitor_id
+    if user_id:
+        payload["user_id"] = str(user_id)
+    if event_id:
+        payload["event_id"] = event_id
+    if revenue is not None:
+        payload["revenue"] = revenue
+    if ip:
+        payload["ip"] = ip
+    if user_agent:
+        payload["user_agent"] = user_agent
+    if identifier:
+        payload["identifier"] = identifier
+
     response = post_with_response("/conversions", payload)
     if not response:
         return ConversionResult(success=False)

{mbuzz-0.2.0 → mbuzz-0.7.3}/src/mbuzz/client/track.py

@@ -1,4 +1,5 @@
 """Track request for event tracking."""
+# NOTE: Session ID removed in 0.7.0 - server handles session resolution
 
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -16,7 +17,6 @@ class TrackResult:
     event_id: Optional[str] = None
     event_type: Optional[str] = None
     visitor_id: Optional[str] = None
-    session_id: Optional[str] = None
 
 
 @dataclass
@@ -25,15 +25,15 @@ class TrackOptions:
 
     event_type: str
     visitor_id: Optional[str] = None
-    session_id: Optional[str] = None
     user_id: Optional[str] = None
     properties: Optional[Dict[str, Any]] = None
     ip: Optional[str] = None
     user_agent: Optional[str] = None
+    identifier: Optional[Dict[str, str]] = None
 
 
 def _resolve_ids(options: TrackOptions) -> TrackOptions:
-    """Resolve visitor/session/user IDs and ip/user_agent from context if not provided."""
+    """Resolve visitor/user IDs and ip/user_agent from context if not provided."""
     ctx = get_context()
     if not ctx:
         return options
@@ -41,11 +41,11 @@ def _resolve_ids(options: TrackOptions) -> TrackOptions:
     return TrackOptions(
         event_type=options.event_type,
         visitor_id=options.visitor_id or ctx.visitor_id,
-        session_id=options.session_id or ctx.session_id,
         user_id=options.user_id or ctx.user_id,
         properties=options.properties,
         ip=options.ip or ctx.ip,
         user_agent=options.user_agent or ctx.user_agent,
+        identifier=options.identifier,
     )
 
 
@@ -66,19 +66,23 @@ def _validate(options: TrackOptions) -> bool:
 
 def _build_payload(options: TrackOptions, properties: Dict[str, Any]) -> Dict[str, Any]:
     """Build API payload from options."""
-    event = {
+    event: Dict[str, Any] = {
         "event_type": options.event_type,
-        "visitor_id": options.visitor_id,
-        "session_id": options.session_id,
-        "user_id": options.user_id,
         "properties": properties,
         "timestamp": datetime.now(timezone.utc).isoformat(),
     }
-    # Add ip and user_agent only if provided (for server-side session resolution)
+
+    # Only include non-None values
+    if options.visitor_id:
+        event["visitor_id"] = options.visitor_id
+    if options.user_id:
+        event["user_id"] = options.user_id
     if options.ip:
         event["ip"] = options.ip
     if options.user_agent:
         event["user_agent"] = options.user_agent
+    if options.identifier:
+        event["identifier"] = options.identifier
 
     return {"events": [event]}
 
@@ -94,29 +98,28 @@ def _parse_response(response: Optional[Dict[str, Any]], options: TrackOptions) -
         event_id=event.get("id"),
         event_type=options.event_type,
         visitor_id=options.visitor_id,
-        session_id=options.session_id,
     )
 
 
 def track(
     event_type: str,
     visitor_id: Optional[str] = None,
-    session_id: Optional[str] = None,
     user_id: Optional[str] = None,
     properties: Optional[Dict[str, Any]] = None,
     ip: Optional[str] = None,
     user_agent: Optional[str] = None,
+    identifier: Optional[Dict[str, str]] = None,
 ) -> TrackResult:
     """Track an event.
 
     Args:
         event_type: Type of event (e.g., "page_view", "button_click")
         visitor_id: Visitor ID (uses context if not provided)
-        session_id: Session ID (uses context if not provided)
         user_id: User ID (uses context if not provided)
         properties: Additional event properties
         ip: Client IP address for server-side session resolution
         user_agent: Client user agent for server-side session resolution
+        identifier: Cross-device identifier (email, user_id, etc.)
 
     Returns:
         TrackResult with success status and event details
@@ -124,11 +127,11 @@ def track(
     options = TrackOptions(
         event_type=event_type,
         visitor_id=visitor_id,
-        session_id=session_id,
         user_id=user_id,
         properties=properties,
         ip=ip,
         user_agent=user_agent,
+        identifier=identifier,
     )
 
     options = _resolve_ids(options)

{mbuzz-0.2.0 → mbuzz-0.7.3}/src/mbuzz/context.py

@@ -1,4 +1,5 @@
 """Request context management using contextvars."""
+# NOTE: Session ID removed in 0.7.0 - server handles session resolution
 
 from contextvars import ContextVar
 from dataclasses import dataclass
@@ -10,12 +11,11 @@ class RequestContext:
     """Holds request-scoped data for tracking."""
 
     visitor_id: str
-    session_id: str
+    ip: str
+    user_agent: str
     user_id: Optional[str] = None
     url: Optional[str] = None
     referrer: Optional[str] = None
-    ip: Optional[str] = None
-    user_agent: Optional[str] = None
 
     def enrich_properties(self, properties: Dict[str, Any]) -> Dict[str, Any]:
         """Add url and referrer to properties if not already present."""

{mbuzz-0.2.0 → mbuzz-0.7.3}/src/mbuzz/cookies.py

@@ -1,7 +1,5 @@
 """Cookie constants for mbuzz SDK."""
+# NOTE: Session cookie removed in 0.7.0 - server handles session resolution
 
 VISITOR_COOKIE = "_mbuzz_vid"
-SESSION_COOKIE = "_mbuzz_sid"
-
 VISITOR_MAX_AGE = 63072000  # 2 years in seconds
-SESSION_MAX_AGE = 1800  # 30 minutes in seconds

mbuzz-0.7.3/src/mbuzz/middleware/flask.py

@@ -0,0 +1,162 @@
+"""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."""
+
+    @app.before_request
+    def before_request():
+        if _should_skip():
+            return
+
+        visitor_id = _get_or_create_visitor_id()
+        ip = _get_client_ip()
+        user_agent = _get_user_agent()
+
+        _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"):
+            return response
+
+        _set_cookies(response)
+        return response
+
+    @app.teardown_request
+    def teardown_request(exception=None):
+        clear_context()
+
+
+def _should_skip() -> bool:
+    """Check if request should skip tracking."""
+    if not config._initialized or not config.enabled:
+        return True
+    if config.should_skip_path(request.path):
+        return True
+    return False
+
+
+def _get_or_create_visitor_id() -> str:
+    """Get visitor ID from cookie or generate new one."""
+    return request.cookies.get(VISITOR_COOKIE) or generate_id()
+
+
+def _get_client_ip() -> str:
+    """Get client IP from request headers."""
+    forwarded = request.headers.get("X-Forwarded-For", "")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.remote_addr or "unknown"
+
+
+def _get_user_agent() -> str:
+    """Get user agent from request."""
+    return request.headers.get("User-Agent", "unknown")
+
+
+def _set_request_context(visitor_id: str, ip: str, user_agent: str) -> None:
+    """Set request context for tracking calls."""
+    ctx = RequestContext(
+        visitor_id=visitor_id,
+        ip=ip,
+        user_agent=user_agent,
+        user_id=None,
+        url=request.url,
+        referrer=request.referrer,
+    )
+    set_context(ctx)
+
+
+def _store_in_g(visitor_id: str) -> None:
+    """Store tracking IDs in Flask g object for after_request."""
+    g.mbuzz_visitor_id = visitor_id
+    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
+
+    response.set_cookie(
+        VISITOR_COOKIE,
+        g.mbuzz_visitor_id,
+        max_age=VISITOR_MAX_AGE,
+        httponly=True,
+        samesite="Lax",
+        secure=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]