mbuzz 0.1.0__tar.gz → 0.2.0__tar.gz

{mbuzz-0.1.0 → mbuzz-0.2.0}/PKG-INFO

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

{mbuzz-0.1.0 → mbuzz-0.2.0}/pyproject.toml

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

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

@@ -8,7 +8,7 @@ from .client.track import track, TrackResult
 from .client.identify import identify
 from .client.conversion import conversion, ConversionResult
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 
 def init(

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

@@ -28,10 +28,12 @@ class TrackOptions:
     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
 
 
 def _resolve_ids(options: TrackOptions) -> TrackOptions:
-    """Resolve visitor/session/user IDs from context if not provided."""
+    """Resolve visitor/session/user IDs and ip/user_agent from context if not provided."""
     ctx = get_context()
     if not ctx:
         return options
@@ -42,6 +44,8 @@ def _resolve_ids(options: TrackOptions) -> TrackOptions:
         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,
     )
 
 
@@ -62,18 +66,21 @@ def _validate(options: TrackOptions) -> bool:
 
 def _build_payload(options: TrackOptions, properties: Dict[str, Any]) -> Dict[str, Any]:
     """Build API payload from options."""
-    return {
-        "events": [
-            {
-                "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(),
-            }
-        ]
+    event = {
+        "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)
+    if options.ip:
+        event["ip"] = options.ip
+    if options.user_agent:
+        event["user_agent"] = options.user_agent
+
+    return {"events": [event]}
 
 
 def _parse_response(response: Optional[Dict[str, Any]], options: TrackOptions) -> TrackResult:
@@ -97,6 +104,8 @@ def track(
     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,
 ) -> TrackResult:
     """Track an event.
 
@@ -106,6 +115,8 @@ def track(
         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
 
     Returns:
         TrackResult with success status and event details
@@ -116,6 +127,8 @@ def track(
         session_id=session_id,
         user_id=user_id,
         properties=properties,
+        ip=ip,
+        user_agent=user_agent,
     )
 
     options = _resolve_ids(options)

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

@@ -14,6 +14,8 @@ class RequestContext:
     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.1.0 → mbuzz-0.2.0}/src/mbuzz/middleware/flask.py

@@ -8,6 +8,7 @@ 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 ..utils.identifier import generate_id
+from ..utils.session_id import generate_deterministic, generate_from_fingerprint
 from ..client.session import create_session
 
 
@@ -55,8 +56,29 @@ def _get_or_create_visitor_id() -> str:
 
 
 def _get_or_create_session_id() -> str:
-    """Get session ID from cookie or generate new one."""
-    return request.cookies.get(SESSION_COOKIE) or generate_id()
+    """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", "")
+    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, session_id: str) -> None:

mbuzz-0.2.0/src/mbuzz/utils/session_id.py

@@ -0,0 +1,39 @@
+"""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.1.0 → mbuzz-0.2.0}/tests/test_client.py

@@ -112,6 +112,100 @@ class TestTrack:
         result = track(event_type="page_view", visitor_id="vid_123")
         assert result.success is False
 
+    # Server-side session resolution tests (v0.2.0+)
+
+    @patch("mbuzz.client.track.post_with_response")
+    def test_accepts_ip_parameter(self, mock_post):
+        """Should accept and forward ip parameter."""
+        mock_post.return_value = {"events": [{"id": "evt_123"}]}
+
+        result = track(
+            event_type="page_view",
+            visitor_id="vid_123",
+            ip="192.168.1.100"
+        )
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["events"][0]["ip"] == "192.168.1.100"
+
+    @patch("mbuzz.client.track.post_with_response")
+    def test_accepts_user_agent_parameter(self, mock_post):
+        """Should accept and forward user_agent parameter."""
+        mock_post.return_value = {"events": [{"id": "evt_123"}]}
+
+        result = track(
+            event_type="page_view",
+            visitor_id="vid_123",
+            user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
+        )
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["events"][0]["user_agent"] == "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
+
+    @patch("mbuzz.client.track.post_with_response")
+    def test_accepts_both_ip_and_user_agent(self, mock_post):
+        """Should accept both ip and user_agent parameters."""
+        mock_post.return_value = {"events": [{"id": "evt_123"}]}
+
+        result = track(
+            event_type="page_view",
+            visitor_id="vid_123",
+            ip="10.0.0.1",
+            user_agent="Chrome/120"
+        )
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["events"][0]["ip"] == "10.0.0.1"
+        assert payload["events"][0]["user_agent"] == "Chrome/120"
+
+    @patch("mbuzz.client.track.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 = {"events": [{"id": "evt_123"}]}
+        set_context(RequestContext(
+            visitor_id="ctx_vid",
+            session_id="ctx_sid",
+            ip="203.0.113.50",
+            user_agent="Safari/17.0"
+        ))
+
+        result = track(event_type="page_view")
+        assert result.success is True
+
+        call_args = mock_post.call_args[0]
+        payload = call_args[1]
+        assert payload["events"][0]["ip"] == "203.0.113.50"
+        assert payload["events"][0]["user_agent"] == "Safari/17.0"
+
+    @patch("mbuzz.client.track.post_with_response")
+    def test_explicit_ip_overrides_context(self, mock_post):
+        """Should use explicit ip/user_agent over context."""
+        mock_post.return_value = {"events": [{"id": "evt_123"}]}
+        set_context(RequestContext(
+            visitor_id="ctx_vid",
+            session_id="ctx_sid",
+            ip="context_ip",
+            user_agent="context_ua"
+        ))
+
+        result = track(
+            event_type="page_view",
+            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["events"][0]["ip"] == "explicit_ip"
+        assert payload["events"][0]["user_agent"] == "explicit_ua"
+
 
 class TestIdentify:
     """Test identify function."""

mbuzz-0.2.0/tests/test_session_id.py

@@ -0,0 +1,146 @@
+"""Tests for deterministic session ID generation."""
+
+import pytest
+from mbuzz.utils.session_id import (
+    generate_deterministic,
+    generate_from_fingerprint,
+    generate_random,
+)
+
+
+class TestGenerateDeterministic:
+    sample_visitor_id = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+    sample_timestamp = 1735500000
+
+    def test_returns_64_char_hex_string(self):
+        result = generate_deterministic(self.sample_visitor_id, self.sample_timestamp)
+        assert len(result) == 64
+        assert all(c in "0123456789abcdef" for c in result)
+
+    def test_is_consistent(self):
+        result1 = generate_deterministic(self.sample_visitor_id, self.sample_timestamp)
+        result2 = generate_deterministic(self.sample_visitor_id, self.sample_timestamp)
+        assert result1 == result2
+
+    def test_same_within_time_bucket(self):
+        # bucket = timestamp / 1800
+        # 1735500000 / 1800 = 964166
+        # 1735500599 / 1800 = 964166 (last second of bucket)
+        timestamp1 = 1735500000
+        timestamp2 = 1735500001
+        timestamp3 = 1735500599
+
+        result1 = generate_deterministic(self.sample_visitor_id, timestamp1)
+        result2 = generate_deterministic(self.sample_visitor_id, timestamp2)
+        result3 = generate_deterministic(self.sample_visitor_id, timestamp3)
+
+        assert result1 == result2
+        assert result1 == result3
+
+    def test_different_across_time_buckets(self):
+        timestamp1 = 1735500000
+        timestamp2 = 1735501800  # Next bucket
+
+        result1 = generate_deterministic(self.sample_visitor_id, timestamp1)
+        result2 = generate_deterministic(self.sample_visitor_id, timestamp2)
+
+        assert result1 != result2
+
+    def test_different_for_different_visitors(self):
+        result1 = generate_deterministic("visitor_a", self.sample_timestamp)
+        result2 = generate_deterministic("visitor_b", self.sample_timestamp)
+
+        assert result1 != result2
+
+
+class TestGenerateFromFingerprint:
+    sample_ip = "203.0.113.42"
+    sample_user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+    sample_timestamp = 1735500000
+
+    def test_returns_64_char_hex_string(self):
+        result = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, self.sample_timestamp
+        )
+        assert len(result) == 64
+        assert all(c in "0123456789abcdef" for c in result)
+
+    def test_is_consistent(self):
+        result1 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, self.sample_timestamp
+        )
+        result2 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, self.sample_timestamp
+        )
+        assert result1 == result2
+
+    def test_same_within_time_bucket(self):
+        timestamp1 = 1735500000
+        timestamp2 = 1735500001
+
+        result1 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, timestamp1
+        )
+        result2 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, timestamp2
+        )
+
+        assert result1 == result2
+
+    def test_different_across_time_buckets(self):
+        timestamp1 = 1735500000
+        timestamp2 = 1735501800
+
+        result1 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, timestamp1
+        )
+        result2 = generate_from_fingerprint(
+            self.sample_ip, self.sample_user_agent, timestamp2
+        )
+
+        assert result1 != result2
+
+    def test_different_for_different_ips(self):
+        result1 = generate_from_fingerprint(
+            "192.168.1.1", self.sample_user_agent, self.sample_timestamp
+        )
+        result2 = generate_from_fingerprint(
+            "192.168.1.2", self.sample_user_agent, self.sample_timestamp
+        )
+
+        assert result1 != result2
+
+    def test_different_for_different_user_agents(self):
+        result1 = generate_from_fingerprint(
+            self.sample_ip, "Mozilla/5.0 Chrome", self.sample_timestamp
+        )
+        result2 = generate_from_fingerprint(
+            self.sample_ip, "Mozilla/5.0 Safari", self.sample_timestamp
+        )
+
+        assert result1 != result2
+
+
+class TestGenerateRandom:
+    def test_returns_64_char_hex_string(self):
+        result = generate_random()
+        assert len(result) == 64
+        assert all(c in "0123456789abcdef" for c in result)
+
+    def test_returns_unique_ids(self):
+        result1 = generate_random()
+        result2 = generate_random()
+        assert result1 != result2
+
+
+class TestCrossMethod:
+    def test_deterministic_and_fingerprint_produce_different_ids(self):
+        visitor_id = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+        ip = "203.0.113.42"
+        user_agent = "Mozilla/5.0"
+        timestamp = 1735500000
+
+        deterministic = generate_deterministic(visitor_id, timestamp)
+        fingerprint = generate_from_fingerprint(ip, user_agent, timestamp)
+
+        assert deterministic != fingerprint