mbuzz 0.2.0__py3-none-any.whl → 0.7.3__py3-none-any.whl

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/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/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/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/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/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/middleware/flask.py

@@ -1,15 +1,44 @@
 """Flask middleware for mbuzz tracking."""
+# NOTE: Session cookie removed in 0.7.0 - server handles session resolution
 
 import threading
-from flask import Flask, request, g, Response
+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, SESSION_COOKIE, VISITOR_MAX_AGE, SESSION_MAX_AGE
+from ..cookies import VISITOR_COOKIE, VISITOR_MAX_AGE
+from ..utils.fingerprint import device_fingerprint
 from ..utils.identifier import generate_id
-from ..utils.session_id import generate_deterministic, generate_from_fingerprint
-from ..client.session import create_session
+
+
+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:
@@ -21,12 +50,16 @@ def init_app(app: Flask) -> None:
             return
 
         visitor_id = _get_or_create_visitor_id()
-        session_id = _get_or_create_session_id()
-        is_new_session = SESSION_COOKIE not in request.cookies
+        ip = _get_client_ip()
+        user_agent = _get_user_agent()
+
+        _set_request_context(visitor_id, ip, user_agent)
+        _store_in_g(visitor_id)
 
-        _set_request_context(visitor_id, session_id)
-        _store_in_g(visitor_id, session_id, is_new_session)
-        _create_session_if_new(visitor_id, session_id, is_new_session)
+        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:
@@ -55,19 +88,6 @@ def _get_or_create_visitor_id() -> str:
     return request.cookies.get(VISITOR_COOKIE) or generate_id()
 
 
-def _get_or_create_session_id() -> str:
-    """Get session ID from cookie or generate deterministic one."""
-    existing = request.cookies.get(SESSION_COOKIE)
-    if existing:
-        return existing
-
-    existing_visitor_id = request.cookies.get(VISITOR_COOKIE)
-    if existing_visitor_id:
-        return generate_deterministic(existing_visitor_id)
-    else:
-        return generate_from_fingerprint(_get_client_ip(), _get_user_agent())
-
-
 def _get_client_ip() -> str:
     """Get client IP from request headers."""
     forwarded = request.headers.get("X-Forwarded-For", "")
@@ -81,11 +101,12 @@ def _get_user_agent() -> str:
     return request.headers.get("User-Agent", "unknown")
 
 
-def _set_request_context(visitor_id: str, session_id: str) -> None:
+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,
-        session_id=session_id,
+        ip=ip,
+        user_agent=user_agent,
         user_id=None,
         url=request.url,
         referrer=request.referrer,
@@ -93,34 +114,42 @@ def _set_request_context(visitor_id: str, session_id: str) -> None:
     set_context(ctx)
 
 
-def _store_in_g(visitor_id: str, session_id: str, is_new_session: bool) -> None:
+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_session_id = session_id
     g.mbuzz_is_new_visitor = VISITOR_COOKIE not in request.cookies
-    g.mbuzz_is_new_session = is_new_session
 
 
-def _create_session_if_new(visitor_id: str, session_id: str, is_new_session: bool) -> None:
-    """Create session asynchronously if new session."""
-    if not is_new_session:
-        return
+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"),
+        }
+    }
 
-    ctx = RequestContext(
-        visitor_id=visitor_id,
-        session_id=session_id,
-        url=request.url,
-        referrer=request.referrer,
-    )
     threading.Thread(
-        target=create_session,
-        args=(visitor_id, session_id, ctx.url, ctx.referrer),
-        daemon=True
+        target=post, args=("/sessions", payload), daemon=True
     ).start()
 
 
 def _set_cookies(response: Response) -> None:
-    """Set visitor and session cookies on response."""
+    """Set visitor cookie on response."""
     secure = request.is_secure
 
     response.set_cookie(
@@ -131,11 +160,3 @@ def _set_cookies(response: Response) -> None:
         samesite="Lax",
         secure=secure,
     )
-    response.set_cookie(
-        SESSION_COOKIE,
-        g.mbuzz_session_id,
-        max_age=SESSION_MAX_AGE,
-        httponly=True,
-        samesite="Lax",
-        secure=secure,
-    )

mbuzz/utils/__init__.py

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

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.2.0.dist-info → mbuzz-0.7.3.dist-info}/METADATA

@@ -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.7.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+mbuzz/__init__.py,sha256=OQDjNSQTB6Yfc66NRpZPN8cWjWcVJopDysoB8tb3cbU,2150
+mbuzz/api.py,sha256=bOLjQRgv9PbfGvNxYMtdyiBQvlLFHsHcVgZ8_lEWEHU,2107
+mbuzz/config.py,sha256=u6v1WnMTgiqyDXHszlXw5hyNENgYRy7-z-IWKuYp0-o,2399
+mbuzz/context.py,sha256=tcvtKaAbHzH8dHGkKviNgXF31IKgintqo0lhb6uU4dU,1308
+mbuzz/cookies.py,sha256=pDcvSq0ulzKrFLf5UK408s9Lv2pVzLANVaF_-P7iG3c,194
+mbuzz/client/__init__.py,sha256=oNOTpPKdt-b_VH_f848OQTbEEDFhlpbEjZ-WjKvh3JI,36
+mbuzz/client/conversion.py,sha256=mUkxU8FgbmvvXnliTskawnDzbwn1SxutZ5E4rFkNt5o,3155
+mbuzz/client/identify.py,sha256=duyd-OWdBo4w7-7Nv5X-GeG2IpMI-1G_kYwnDXup0FE,859
+mbuzz/client/track.py,sha256=NReHqXWx24cPhIlc7UBQjj9QVdnXfrJsFzS5UmOUMtA,4354
+mbuzz/middleware/__init__.py,sha256=gIjwTArToaQNB2NC0iPE_RcmzuHjH7-7jjd7_Dyq4Pw,37
+mbuzz/middleware/flask.py,sha256=gkvwtgfLasTKq64lUvK_9I2PeOR9oBRbrWpQZbqnaAk,4656
+mbuzz/utils/__init__.py,sha256=tq5wgr4Cy-PFl2tvpN5VYHzPd3M-e5qcxnv-McoTopI,169
+mbuzz/utils/fingerprint.py,sha256=T2plrP9n70LkoCvGbBCh7nxZRfdQpCd_CdZBseBfzCg,410
+mbuzz/utils/identifier.py,sha256=iAYmd4he2RTtTNlmszb6KQmD9McZbSMgZZdkMuoGOCE,174
+mbuzz-0.7.3.dist-info/METADATA,sha256=Q0dHPns1Lk73_ziPwsknxzQMIkJFAYnqRo5drKkCD_0,1849
+mbuzz-0.7.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mbuzz-0.7.3.dist-info/RECORD,,

mbuzz/client/session.py

@@ -1,38 +0,0 @@
-"""Session request for creating sessions."""
-
-from datetime import datetime, timezone
-from typing import Optional
-
-from ..api import post
-
-
-def create_session(
-    visitor_id: str,
-    session_id: str,
-    url: str,
-    referrer: Optional[str] = None,
-) -> bool:
-    """Create a new session.
-
-    Called async from middleware on first request.
-
-    Args:
-        visitor_id: Visitor ID
-        session_id: Session ID
-        url: Current page URL
-        referrer: Referring URL
-
-    Returns:
-        True on success, False on failure
-    """
-    payload = {
-        "session": {
-            "visitor_id": visitor_id,
-            "session_id": session_id,
-            "url": url,
-            "referrer": referrer,
-            "started_at": datetime.now(timezone.utc).isoformat(),
-        }
-    }
-
-    return post("/sessions", payload)

mbuzz/utils/session_id.py

@@ -1,39 +0,0 @@
-"""Deterministic session ID generation."""
-
-import hashlib
-import secrets
-import time
-
-SESSION_TIMEOUT_SECONDS = 1800
-SESSION_ID_LENGTH = 64
-FINGERPRINT_LENGTH = 32
-
-
-def generate_deterministic(visitor_id: str, timestamp: int | None = None) -> str:
-    """Generate session ID for returning visitors."""
-    if timestamp is None:
-        timestamp = int(time.time())
-    time_bucket = timestamp // SESSION_TIMEOUT_SECONDS
-    raw = f"{visitor_id}_{time_bucket}"
-    return hashlib.sha256(raw.encode()).hexdigest()[:SESSION_ID_LENGTH]
-
-
-def generate_from_fingerprint(
-    client_ip: str,
-    user_agent: str,
-    timestamp: int | None = None
-) -> str:
-    """Generate session ID for new visitors using IP+UA fingerprint."""
-    if timestamp is None:
-        timestamp = int(time.time())
-    fingerprint = hashlib.sha256(
-        f"{client_ip}|{user_agent}".encode()
-    ).hexdigest()[:FINGERPRINT_LENGTH]
-    time_bucket = timestamp // SESSION_TIMEOUT_SECONDS
-    raw = f"{fingerprint}_{time_bucket}"
-    return hashlib.sha256(raw.encode()).hexdigest()[:SESSION_ID_LENGTH]
-
-
-def generate_random() -> str:
-    """Generate random session ID (fallback)."""
-    return secrets.token_hex(32)

mbuzz-0.2.0.dist-info/RECORD

@@ -1,18 +0,0 @@
-mbuzz/__init__.py,sha256=ip9lSCsNe7T5k1qOfGs4pttoTNGx5Ws-Zf9fHoWXFPg,2247
-mbuzz/api.py,sha256=BITkW6TQEGmPA0OmYFFC611X6JWiY6C1dY-_wsKDT2U,2107
-mbuzz/config.py,sha256=u6v1WnMTgiqyDXHszlXw5hyNENgYRy7-z-IWKuYp0-o,2399
-mbuzz/context.py,sha256=mM9Hi8GnqTkAVCqB_VKGCXl7a5AFME4WTM-2DCIji_w,1290
-mbuzz/cookies.py,sha256=MCpMljQXaqJ2bhEtTv1aKR2fuqLfGBFofjPRayAQGpw,197
-mbuzz/client/__init__.py,sha256=oNOTpPKdt-b_VH_f848OQTbEEDFhlpbEjZ-WjKvh3JI,36
-mbuzz/client/conversion.py,sha256=Ua3ngFWmH6ekm3ZanNf5up_jV8t5nf788ipM1usvZoM,2346
-mbuzz/client/identify.py,sha256=duyd-OWdBo4w7-7Nv5X-GeG2IpMI-1G_kYwnDXup0FE,859
-mbuzz/client/session.py,sha256=mk8v892bvpeW-VNKFQYDsW442w881yfXBiM4sr9a0SU,835
-mbuzz/client/track.py,sha256=HWRYWDWJ_WW_k5IHtkAn4s_MmVwSVFxsxR76KG2h_Ps,4288
-mbuzz/middleware/__init__.py,sha256=gIjwTArToaQNB2NC0iPE_RcmzuHjH7-7jjd7_Dyq4Pw,37
-mbuzz/middleware/flask.py,sha256=s3U77A2986L-KvWUH9MmqSwJwQWzQTYlZPZXH-wzE9o,4182
-mbuzz/utils/__init__.py,sha256=-ejtRN6CTkV3D8uujDtAPDoMT0DAG-ULpWOF-Ae55dY,103
-mbuzz/utils/identifier.py,sha256=iAYmd4he2RTtTNlmszb6KQmD9McZbSMgZZdkMuoGOCE,174
-mbuzz/utils/session_id.py,sha256=3XJkzPg5iUIbRYzz5LThfS8WTAmlmtn60WZTA_TlVhk,1185
-mbuzz-0.2.0.dist-info/METADATA,sha256=3Z8snpq6fv0PmZUvSuAjsH1KaiZIpE9pRLVHTaw8cPE,1849
-mbuzz-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mbuzz-0.2.0.dist-info/RECORD,,