mbuzz 0.1.0__tar.gz

mbuzz-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local development
+.env
+.env.local

mbuzz-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mbuzz
+Version: 0.1.0
+Summary: Multi-touch attribution SDK for Python
+Project-URL: Homepage, https://mbuzz.co
+Project-URL: Documentation, https://mbuzz.co/docs/getting-started
+Project-URL: Repository, https://github.com/mbuzzco/mbuzz-python
+Author-email: Mbuzz <support@mbuzz.co>
+License-Expression: MIT
+Keywords: analytics,attribution,marketing,tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: django
+Provides-Extra: fastapi
+Requires-Dist: starlette; extra == 'fastapi'
+Provides-Extra: flask
+Description-Content-Type: text/markdown
+
+# mbuzz-python
+
+Python SDK for mbuzz multi-touch attribution.
+
+## Installation
+
+```bash
+pip install mbuzz
+```
+
+## Quick Start
+
+```python
+import mbuzz
+
+# Initialize (once on app start)
+mbuzz.init(api_key="sk_live_...")
+
+# Track events
+mbuzz.event("page_view", url="/pricing")
+
+# Track conversions
+mbuzz.conversion("purchase", revenue=99.99)
+
+# Identify users
+mbuzz.identify("user_123", traits={"email": "user@example.com"})
+```
+
+## Documentation
+
+See [mbuzz.co/docs/getting-started](https://mbuzz.co/docs/getting-started) for full documentation.

mbuzz-0.1.0/README.md

@@ -0,0 +1,31 @@
+# mbuzz-python
+
+Python SDK for mbuzz multi-touch attribution.
+
+## Installation
+
+```bash
+pip install mbuzz
+```
+
+## Quick Start
+
+```python
+import mbuzz
+
+# Initialize (once on app start)
+mbuzz.init(api_key="sk_live_...")
+
+# Track events
+mbuzz.event("page_view", url="/pricing")
+
+# Track conversions
+mbuzz.conversion("purchase", revenue=99.99)
+
+# Identify users
+mbuzz.identify("user_123", traits={"email": "user@example.com"})
+```
+
+## Documentation
+
+See [mbuzz.co/docs/getting-started](https://mbuzz.co/docs/getting-started) for full documentation.

mbuzz-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mbuzz"
+version = "0.1.0"
+description = "Multi-touch attribution SDK for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "Mbuzz", email = "support@mbuzz.co" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django",
+    "Framework :: Flask",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+keywords = ["analytics", "attribution", "marketing", "tracking"]
+
+[project.urls]
+Homepage = "https://mbuzz.co"
+Documentation = "https://mbuzz.co/docs/getting-started"
+Repository = "https://github.com/mbuzzco/mbuzz-python"
+
+[project.optional-dependencies]
+django = []
+flask = []
+fastapi = ["starlette"]
+dev = ["pytest", "pytest-cov", "black", "ruff", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mbuzz"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.8"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mbuzz-0.1.0/src/mbuzz/__init__.py

@@ -0,0 +1,87 @@
+"""Mbuzz - Multi-touch attribution SDK for Python."""
+
+from typing import Any, Dict, Optional, Union
+
+from .config import config
+from .context import get_context
+from .client.track import track, TrackResult
+from .client.identify import identify
+from .client.conversion import conversion, ConversionResult
+
+__version__ = "0.1.0"
+
+
+def init(
+    api_key: str,
+    api_url: Optional[str] = None,
+    enabled: bool = True,
+    debug: bool = False,
+    timeout: Optional[float] = None,
+    skip_paths: Optional[list] = None,
+    skip_extensions: Optional[list] = None,
+) -> None:
+    """Initialize the mbuzz SDK.
+
+    Args:
+        api_key: Your mbuzz API key (required)
+        api_url: API endpoint URL (default: https://mbuzz.co/api/v1)
+        enabled: Enable/disable tracking (default: True)
+        debug: Enable debug logging (default: False)
+        timeout: Request timeout in seconds (default: 5.0)
+        skip_paths: Additional paths to skip tracking
+        skip_extensions: Additional file extensions to skip
+    """
+    config.init(
+        api_key=api_key,
+        api_url=api_url,
+        enabled=enabled,
+        debug=debug,
+        timeout=timeout,
+        skip_paths=skip_paths or [],
+        skip_extensions=skip_extensions or [],
+    )
+
+
+def event(event_type: str, **properties: Any) -> TrackResult:
+    """Track an event.
+
+    Args:
+        event_type: Type of event (e.g., "page_view", "button_click")
+        **properties: Additional event properties
+
+    Returns:
+        TrackResult with success status and event details
+    """
+    return track(event_type=event_type, properties=properties)
+
+
+def visitor_id() -> Optional[str]:
+    """Get current visitor ID from context."""
+    ctx = get_context()
+    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()
+    return ctx.user_id if ctx else None
+
+
+__all__ = [
+    "init",
+    "event",
+    "conversion",
+    "identify",
+    "visitor_id",
+    "session_id",
+    "user_id",
+    "TrackResult",
+    "ConversionResult",
+    "__version__",
+]

mbuzz-0.1.0/src/mbuzz/api.py

@@ -0,0 +1,71 @@
+"""HTTP client for mbuzz API communication."""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+from .config import config
+
+logger = logging.getLogger("mbuzz")
+
+VERSION = "0.1.0"
+
+
+def post(path: str, payload: Dict[str, Any]) -> bool:
+    """POST to API, return True on success, False on any failure.
+
+    Never raises exceptions - all errors are caught and logged.
+    """
+    if not config._initialized or not config.enabled:
+        return False
+
+    try:
+        response = _make_request(path, payload)
+        return 200 <= response.status < 300
+    except Exception as e:
+        if config.debug:
+            logger.error(f"mbuzz API error: {e}")
+        return False
+
+
+def post_with_response(path: str, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """POST to API, return parsed JSON on success, None on failure.
+
+    Never raises exceptions - all errors are caught and logged.
+    """
+    if not config._initialized or not config.enabled:
+        return None
+
+    try:
+        response = _make_request(path, payload)
+        if 200 <= response.status < 300:
+            body = response.read().decode("utf-8")
+            if config.debug:
+                logger.debug(f"mbuzz response: {body}")
+            return json.loads(body)
+        return None
+    except Exception as e:
+        if config.debug:
+            logger.error(f"mbuzz API error: {e}")
+        return None
+
+
+def _make_request(path: str, payload: Dict[str, Any]):
+    """Make HTTP request to API."""
+    base_url = config.api_url.rstrip("/")
+    clean_path = path.lstrip("/")
+    url = f"{base_url}/{clean_path}"
+
+    data = json.dumps(payload).encode("utf-8")
+
+    req = Request(url, data=data, method="POST")
+    req.add_header("Authorization", f"Bearer {config.api_key}")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("User-Agent", f"mbuzz-python/{VERSION}")
+
+    if config.debug:
+        logger.debug(f"mbuzz POST {url}: {payload}")
+
+    return urlopen(req, timeout=config.timeout)

mbuzz-0.1.0/src/mbuzz/client/__init__.py

@@ -0,0 +1 @@
+"""Client module - stub for TDD."""

mbuzz-0.1.0/src/mbuzz/client/conversion.py

@@ -0,0 +1,74 @@
+"""Conversion request for tracking conversions."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Union
+
+from ..api import post_with_response
+from ..context import get_context
+
+
+@dataclass
+class ConversionResult:
+    """Result of tracking a conversion."""
+
+    success: bool
+    conversion_id: Optional[str] = None
+    attribution: Optional[Dict[str, Any]] = None
+
+
+def conversion(
+    conversion_type: str,
+    visitor_id: Optional[str] = None,
+    user_id: Optional[Union[str, int]] = None,
+    event_id: Optional[str] = None,
+    revenue: Optional[float] = None,
+    currency: str = "USD",
+    is_acquisition: bool = False,
+    inherit_acquisition: bool = False,
+    properties: Optional[Dict[str, Any]] = None,
+) -> ConversionResult:
+    """Track a conversion.
+
+    Args:
+        conversion_type: Type of conversion (e.g., "purchase", "signup")
+        visitor_id: Visitor ID (uses context if not provided)
+        user_id: User ID (uses context if not provided)
+        event_id: Optional event ID to link conversion to
+        revenue: Revenue amount
+        currency: Currency code (default: USD)
+        is_acquisition: Whether this is a customer acquisition
+        inherit_acquisition: Whether to inherit acquisition from previous conversion
+        properties: Additional conversion properties
+
+    Returns:
+        ConversionResult with success status, conversion ID, and attribution data
+    """
+    ctx = get_context()
+
+    visitor_id = visitor_id or (ctx.visitor_id if ctx else None)
+    user_id = user_id or (ctx.user_id if ctx else None)
+
+    if not visitor_id and not user_id:
+        return ConversionResult(success=False)
+
+    payload = {
+        "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 {},
+    }
+
+    response = post_with_response("/conversions", payload)
+    if not response:
+        return ConversionResult(success=False)
+
+    return ConversionResult(
+        success=True,
+        conversion_id=response.get("conversion", {}).get("id"),
+        attribution=response.get("attribution"),
+    )

mbuzz-0.1.0/src/mbuzz/client/identify.py

@@ -0,0 +1,36 @@
+"""Identify request for user identification."""
+
+from typing import Any, Dict, Optional, Union
+
+from ..api import post
+from ..context import get_context
+
+
+def identify(
+    user_id: Union[str, int, None],
+    visitor_id: Optional[str] = None,
+    traits: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Identify a user and link to visitor.
+
+    Args:
+        user_id: User ID to identify (required)
+        visitor_id: Visitor ID (uses context if not provided)
+        traits: User traits/attributes
+
+    Returns:
+        True on success, False on failure
+    """
+    if not user_id:
+        return False
+
+    ctx = get_context()
+    visitor_id = visitor_id or (ctx.visitor_id if ctx else None)
+
+    payload = {
+        "user_id": str(user_id),
+        "visitor_id": visitor_id,
+        "traits": traits or {},
+    }
+
+    return post("/identify", payload)

mbuzz-0.1.0/src/mbuzz/client/session.py

@@ -0,0 +1,38 @@
+"""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-0.1.0/src/mbuzz/client/track.py

@@ -0,0 +1,130 @@
+"""Track request for event tracking."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from ..api import post_with_response
+from ..context import get_context
+
+
+@dataclass
+class TrackResult:
+    """Result of tracking an event."""
+
+    success: bool
+    event_id: Optional[str] = None
+    event_type: Optional[str] = None
+    visitor_id: Optional[str] = None
+    session_id: Optional[str] = None
+
+
+@dataclass
+class TrackOptions:
+    """Options for tracking an event."""
+
+    event_type: str
+    visitor_id: Optional[str] = None
+    session_id: Optional[str] = None
+    user_id: Optional[str] = None
+    properties: Optional[Dict[str, Any]] = None
+
+
+def _resolve_ids(options: TrackOptions) -> TrackOptions:
+    """Resolve visitor/session/user IDs from context if not provided."""
+    ctx = get_context()
+    if not ctx:
+        return options
+
+    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,
+    )
+
+
+def _enrich_properties(options: TrackOptions) -> Dict[str, Any]:
+    """Enrich properties with url/referrer from context."""
+    ctx = get_context()
+    props = options.properties or {}
+
+    if ctx:
+        return ctx.enrich_properties(props)
+    return props
+
+
+def _validate(options: TrackOptions) -> bool:
+    """Validate track options. Must have visitor_id or user_id."""
+    return bool(options.visitor_id or options.user_id)
+
+
+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(),
+            }
+        ]
+    }
+
+
+def _parse_response(response: Optional[Dict[str, Any]], options: TrackOptions) -> TrackResult:
+    """Parse API response into TrackResult."""
+    if not response or not response.get("events"):
+        return TrackResult(success=False)
+
+    event = response["events"][0]
+    return TrackResult(
+        success=True,
+        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,
+) -> 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
+
+    Returns:
+        TrackResult with success status and event details
+    """
+    options = TrackOptions(
+        event_type=event_type,
+        visitor_id=visitor_id,
+        session_id=session_id,
+        user_id=user_id,
+        properties=properties,
+    )
+
+    options = _resolve_ids(options)
+
+    if not _validate(options):
+        return TrackResult(success=False)
+
+    enriched_props = _enrich_properties(options)
+    payload = _build_payload(options, enriched_props)
+    response = post_with_response("/events", payload)
+
+    return _parse_response(response, options)