eventflows 0.1.0__tar.gz

eventflows-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Poetry
+poetry.lock
+
+# VS Code / IDEs
+.vscode/
+.idea/
+*.swp
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build files
+dist/
+build/
+*.egg-info/

eventflows-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: eventflows
+Version: 0.1.0
+Summary: A robust, non-blocking server-side event tracking library.
+Author-email: Raghav <raghav@23v.co>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic[email]>=2.12.5
+Requires-Dist: httpx>=0.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.9; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+
+Here's the cleaned-up and properly formatted version of your markdown:
+
+---
+
+# EventFlows
+
+A lightweight, robust, and privacy-first server-side tracking library for Python.
+
+EventFlows acts as a universal router for your conversion events. You define your tracking event once, and EventFlows automatically cleans it, hashes sensitive PII, batches it in a background thread, and safely dispatches it to multiple external APIs (Meta, GA4, Reddit, TikTok) without slowing down your main application.
+
+---
+
+## Key Features
+
+* **Zero Latency:** Events are dropped into a thread-safe memory queue instantly. Your users never wait for a tracking pixel to load.
+* **Privacy by Design:** Emails and phone numbers are automatically normalized and SHA-256 hashed before they ever leave your server.
+* **Smart Payload Mapping:** Send custom data freely. EventFlows dynamically formats it for "Open" APIs (like Meta) and strictly filters it for "Rigid" APIs (like Reddit).
+* **Destination Filtering:** Choose exactly which networks receive which events.
+* **Resilient Networking:** Built-in exponential backoff and retry logic for network blips or rate limits.
+
+---
+
+## Installation
+
+Currently, EventFlows is installed from source.
+
+### Using Poetry
+
+```bash
+poetry add git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+### Using pip
+
+```bash
+pip install git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+---
+
+## Quickstart
+
+Register your providers once at the start of your application, then use `tracker.track` anywhere.
+
+```python
+import logging
+from EventFlows import tracker, EventType
+from EventFlows import ConsoleProvider, MetaProvider, RedditProvider, GA4Provider
+
+# Setup logging to see EventFlows processing in the background
+logging.basicConfig(level=logging.INFO)
+
+# 1. Register your destinations (Providers)
+tracker.add_provider(ConsoleProvider())  # Great for local debugging
+tracker.add_provider(MetaProvider(pixel_id="123", access_token="abc"))
+tracker.add_provider(GA4Provider(measurement_id="G-123", api_secret="abc"))
+
+# 2. Track an event anywhere in your app
+# This happens instantly. Hashing and API calls occur in a background thread.
+tracker.track(
+    name="ProSubscription",
+    event_type=EventType.PURCHASE,
+    user_data={
+        "email": "  User@Example.com  ",  # Automatically trimmed, lowercased, and SHA-256 hashed
+        "ip_address": "192.168.1.1"
+    },
+    properties={
+        "value": 49.99,
+        "currency": "USD",
+        "plan_type": "annual"
+    },
+    event_id="ORD-9999"  # Used for server-side deduplication
+)
+
+# 3. Graceful Shutdown
+# Essential for ensuring the memory queue is flushed before the process exits.
+# Call this in your app's shutdown/cleanup hook.
+tracker.shutdown()
+```
+
+---
+
+## Why use `tracker.shutdown()`?
+
+EventFlows uses an internal queue to batch events and keep your application fast. If your script or server exits abruptly without calling `shutdown()`, events still in the queue may not be delivered.
+
+* **FastAPI/Starlette:** Use the `@app.on_event("shutdown")` decorator (or lifespan context manager).
+* **Flask:** Use `atexit.register(tracker.shutdown)`.
+* **Scripts:** Call it as the final line of your execution.

eventflows-0.1.0/README.md

@@ -0,0 +1,89 @@
+Here's the cleaned-up and properly formatted version of your markdown:
+
+---
+
+# EventFlows
+
+A lightweight, robust, and privacy-first server-side tracking library for Python.
+
+EventFlows acts as a universal router for your conversion events. You define your tracking event once, and EventFlows automatically cleans it, hashes sensitive PII, batches it in a background thread, and safely dispatches it to multiple external APIs (Meta, GA4, Reddit, TikTok) without slowing down your main application.
+
+---
+
+## Key Features
+
+* **Zero Latency:** Events are dropped into a thread-safe memory queue instantly. Your users never wait for a tracking pixel to load.
+* **Privacy by Design:** Emails and phone numbers are automatically normalized and SHA-256 hashed before they ever leave your server.
+* **Smart Payload Mapping:** Send custom data freely. EventFlows dynamically formats it for "Open" APIs (like Meta) and strictly filters it for "Rigid" APIs (like Reddit).
+* **Destination Filtering:** Choose exactly which networks receive which events.
+* **Resilient Networking:** Built-in exponential backoff and retry logic for network blips or rate limits.
+
+---
+
+## Installation
+
+Currently, EventFlows is installed from source.
+
+### Using Poetry
+
+```bash
+poetry add git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+### Using pip
+
+```bash
+pip install git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+---
+
+## Quickstart
+
+Register your providers once at the start of your application, then use `tracker.track` anywhere.
+
+```python
+import logging
+from EventFlows import tracker, EventType
+from EventFlows import ConsoleProvider, MetaProvider, RedditProvider, GA4Provider
+
+# Setup logging to see EventFlows processing in the background
+logging.basicConfig(level=logging.INFO)
+
+# 1. Register your destinations (Providers)
+tracker.add_provider(ConsoleProvider())  # Great for local debugging
+tracker.add_provider(MetaProvider(pixel_id="123", access_token="abc"))
+tracker.add_provider(GA4Provider(measurement_id="G-123", api_secret="abc"))
+
+# 2. Track an event anywhere in your app
+# This happens instantly. Hashing and API calls occur in a background thread.
+tracker.track(
+    name="ProSubscription",
+    event_type=EventType.PURCHASE,
+    user_data={
+        "email": "  User@Example.com  ",  # Automatically trimmed, lowercased, and SHA-256 hashed
+        "ip_address": "192.168.1.1"
+    },
+    properties={
+        "value": 49.99,
+        "currency": "USD",
+        "plan_type": "annual"
+    },
+    event_id="ORD-9999"  # Used for server-side deduplication
+)
+
+# 3. Graceful Shutdown
+# Essential for ensuring the memory queue is flushed before the process exits.
+# Call this in your app's shutdown/cleanup hook.
+tracker.shutdown()
+```
+
+---
+
+## Why use `tracker.shutdown()`?
+
+EventFlows uses an internal queue to batch events and keep your application fast. If your script or server exits abruptly without calling `shutdown()`, events still in the queue may not be delivered.
+
+* **FastAPI/Starlette:** Use the `@app.on_event("shutdown")` decorator (or lifespan context manager).
+* **Flask:** Use `atexit.register(tracker.shutdown)`.
+* **Scripts:** Call it as the final line of your execution.

eventflows-0.1.0/demo.py

@@ -0,0 +1,83 @@
+import time
+import logging
+from eventflow import (
+    tracker,
+    EventType,
+    RedditProvider,
+    MetaProvider,
+    GA4Provider,
+    ConsoleProvider,
+)
+
+logging.basicConfig(level=logging.INFO)
+
+# reddit = RedditProvider(
+#     pixel_id="t2_12345", access_token="secret_token_abc", test_mode=True
+# )
+
+# # tracker.add_provider(reddit)
+# reddit_token = "dummy"
+
+# tracker.add_provider(
+#     RedditProvider(pixel_id="t2_123", access_token=reddit_token, test_mode=True)
+# )
+# tracker.add_provider(MetaProvider(pixel_id="123456", access_token="fake"))
+# tracker.add_provider(GA4Provider(measurement_id="G-12345", api_secret="fake"))
+# # tracker.add_provider(MarsenAI(measurement_id="G-12345", api_secret="fake"))
+
+
+# print("Application Started. Tracking events...")
+
+# # tracker.track(
+# #     name="ProSubscription",
+# #     event_type=EventType.CUSTOM,
+# #     user_data={
+# #         "email": "  John.Doe@Gmail.com  ",
+# #         "ip_address": "192.168.1.5",
+# #         "user_agent": "Mozilla/5.0...",
+# #     },
+# #     properties={"value": 29.99, "currency": "USD", "order_id": "ORD-555"},
+# # )
+
+
+# tracker.track(
+#     name="SubscriptionRenewal",
+#     event_type=EventType.CUSTOM,
+#     user_data={
+#         "email": "  John.Doe@Gmail.com  ",
+#         "ip_address": "192.168.1.5",
+#         "user_agent": "Mozilla/5.0...",
+#     },
+#     properties={"value": 30.0, "currency": "USD", "order_id": "ORD-555"},
+# )
+
+# # tracker.track(
+# #     name="Newsletter",
+# #     event_type=EventType.SIGN_UP,
+# #     user_data={"email": "jane@example.com"},
+# # )
+
+
+# # print("Main thread finished work instantly.")
+# # print("Waiting a few seconds to let background worker flush the batch...")
+
+
+# Add Providers
+tracker.add_provider(ConsoleProvider())
+tracker.add_provider(GA4Provider(measurement_id="G-123", api_secret="fake"))
+tracker.add_provider(MetaProvider(pixel_id="123", access_token="fake"))
+tracker.add_provider(RedditProvider(pixel_id="t2_123", access_token="fake"))
+
+print("🚀 Firing restricted event...")
+
+# Track Event - but block the ad networks!
+tracker.track(
+    name="Internal_Password_Reset",
+    user_data={"email": "admin@example.com"},
+    exclude_providers=["meta_capi", "reddit", "tiktok"],  # Block these!
+)
+
+time.sleep(3)
+
+
+# time.sleep(3)

eventflows-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eventflows"
+version = "0.1.0"
+description = "A robust, non-blocking server-side event tracking library."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  {name = "Raghav", email = "raghav@23v.co"}
+]
+license = {text = "MIT"}
+dependencies = [
+    "pydantic[email]>=2.12.5",
+    "httpx>=0.26.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.1.9",
+    "mypy>=1.8.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.mypy]
+# Corrected from 'tool.numpy' in your original file
+strict = true
+ignore_missing_imports = true

eventflows-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eventflows-0.1.0/src/eventflow/__init__.py

@@ -0,0 +1,23 @@
+from .client import tracker, EventFlow
+from .core.events import Event, UserData, EventType
+from .providers.base import BaseProvider
+from .providers.console import ConsoleProvider
+from .providers.reddit import RedditProvider
+from .providers.meta import MetaProvider
+from .providers.google import GA4Provider
+from .providers.tiktok import TikTokProvider
+
+
+__all__ = [
+    "tracker",
+    "EventFlow",
+    "Event",
+    "UserData",
+    "EventType",
+    "BaseProvider",
+    "RedditProvider",
+    "MetaProvider",
+    "GA4Provider",
+    "TikTokProvider",
+    "ConsoleProvider",
+]

eventflows-0.1.0/src/eventflow/client.py

@@ -0,0 +1,66 @@
+import logging
+from typing import List, Optional, Dict, Any
+from .core.events import Event, UserData, EventType
+from .core.queue import SafeQueue
+from .core.worker import BackgroundWorker
+from .providers.base import BaseProvider
+
+logging.getLogger("eventflow").addHandler(logging.NullHandler())
+
+
+class EventFlow:
+
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super(EventFlow, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self, batch_size: int = 10, max_queue_size: int = 1000):
+        if self._initialized:
+            return
+
+        self._providers: List[BaseProvider] = []
+        self._queue = SafeQueue(max_size=max_queue_size)
+        self._worker: Optional[BackgroundWorker] = None
+        self._batch_size = batch_size
+        self._initialized = True
+
+    def add_provider(self, provider: BaseProvider):
+
+        self._providers.append(provider)
+        if not self._worker:
+            self._worker = BackgroundWorker(
+                self._queue, self._providers, self._batch_size
+            )
+
+    def track(
+        self,
+        name: str,
+        user_data: Dict[str, Any] = None,
+        properties: Dict[str, Any] = None,
+        event_type: EventType = EventType.CUSTOM,
+        exclude_providers: List[str] = None,
+    ) -> bool:
+
+        try:
+            user = UserData(**(user_data or {}))
+
+            event = Event(
+                name=name,
+                type=event_type,
+                user=user,
+                properties=properties or {},
+                exclude_providers=exclude_providers or [],
+            )
+
+            return self._queue.put(event)
+
+        except Exception as e:
+            logging.error(f"[EventFlow] Tracking failed: {e}")
+            return False
+
+
+tracker = EventFlow()

eventflows-0.1.0/src/eventflow/core/events.py

@@ -0,0 +1,82 @@
+import hashlib
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, EmailStr, Field, field_validator, ConfigDict, HttpUrl
+
+
+class EventType(str, Enum):
+    PAGE_VIEW = "page_view"
+    SIGN_UP = "sign_up"
+    PURCHASE = "purchase"
+    ADD_TO_CART = "add_to_cart"
+    LEAD = "lead"
+    SEARCH = "search"
+    CUSTOM = "custom"
+
+
+class UserData(BaseModel):
+    """
+    Represents the user triggering the event.
+    CRITICAL: Automatically hashes PII (Email/Phone) upon creation.
+    """
+
+    user_id: Optional[str] = Field(
+        None, description="Internal User ID from your database"
+    )
+    email: Optional[str] = Field(None, description="User email address (Hashed)")
+    phone: Optional[str] = Field(None, description="User phone number (Hashed)")
+    ip_address: Optional[str] = Field(None, description="Client IP Address")
+    user_agent: Optional[str] = Field(None, description="Client User Agent")
+    click_id: Optional[str] = Field(None, description="Click ID (fbc, gclid, etc.)")
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("email", mode="before")
+    @classmethod
+    def hash_email(cls, v: Any) -> Optional[str]:
+        if v and isinstance(v, str):
+            raw_value = v
+            clean_value = raw_value.strip().lower()
+
+            # DEBUG: Prove we are using the right variable
+            # print(f"DEBUG: Hashing '{clean_value}' (Clean) instead of '{raw_value}' (Raw)")
+
+            # CRITICAL: We encode 'clean_value', NOT 'raw_value' or 'v'
+            return hashlib.sha256(clean_value.encode("utf-8")).hexdigest()
+        return v
+
+    @field_validator("phone", mode="before")
+    @classmethod
+    def hash_phone(cls, v: Any) -> Optional[str]:
+        """Normalize (digits only) and SHA-256 hash the phone number."""
+        if v and isinstance(v, str):
+            # Remove spaces, dashes, parentheses
+            clean = "".join(filter(str.isdigit, v))
+            return hashlib.sha256(clean.encode("utf-8")).hexdigest()
+        return v
+
+
+class Event(BaseModel):
+    name: str = Field(
+        ..., min_length=1, description="The name of the event (e.g., 'UserRegistered')"
+    )
+    type: EventType = Field(default=EventType.CUSTOM)
+    user: UserData = Field(default_factory=UserData)
+    properties: Dict[str, Any] = Field(
+        default_factory=dict, description="Custom metadata (price, currency, etc.)"
+    )
+    url: Optional[HttpUrl] = Field(
+        None, description="The page URL where event occurred"
+    )
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    event_id: Optional[str] = Field(
+        None, description="Deduplication ID(e.g., order_id)"
+    )
+
+    exclude_providers: list[str] = Field(
+        default_factory=list, description="Name of providers to exclude"
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")

eventflows-0.1.0/src/eventflow/core/queue.py

@@ -0,0 +1,44 @@
+import queue
+import asyncio
+import logging
+from typing import Optional, Union
+from .events import Event
+
+logger = logging.getLogger("eventflow.queue")
+
+
+class SafeQueue:
+
+    def __init__(self, max_size: int = 1000):
+        self._queue: queue.Queue = queue.Queue(maxsize=max_size)
+        self._dropped_events: int = 0
+
+    def put(self, event: Event) -> bool:
+
+        try:
+            self._queue.put_nowait(event)
+            return True
+        except queue.Full:
+            self._dropped_events += 1
+            if self._dropped_events % 100 == 1:
+                logger.warning(
+                    f"EventFlow Queue is full! Dropped {self._dropped_events} events so far. "
+                    "Check your network connection or increase buffer size."
+                )
+            return False
+
+    def get(self, timeout: float = 0.1) -> Optional[Event]:
+
+        try:
+            return self._queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def task_done(self):
+        self._queue.task_done()
+
+    def qsize(self) -> int:
+        return self._queue.qsize()
+
+    def empty(self) -> bool:
+        return self._queue.empty()

eventflows-0.1.0/src/eventflow/core/worker.py

@@ -0,0 +1,72 @@
+import threading
+import time
+import atexit
+import logging
+from typing import List, Callable, Any
+from .queue import SafeQueue
+from .events import Event
+
+logger = logging.getLogger("eventflow.worker")
+
+
+class BackgroundWorker:
+    def __init__(self, queue: SafeQueue, providers: List[Any], batch_size: int = 10):
+        self._queue = queue
+        self._providers = providers
+        self._batch_size = batch_size
+        self._stop_event = threading.Event()
+
+        self._thread = threading.Thread(
+            target=self._run_loop, name="EventFlow-Worker", daemon=True
+        )
+
+        self._thread.start()
+        atexit.register(self.shutdown)
+
+    def _run_loop(self):
+        logger.debug("EventFlow background worker started.")
+
+        while not self._stop_event.is_set():
+            batch = self._collect_batch()
+            if batch:
+                self._dispatch_batch(batch)
+
+    def _collect_batch(self) -> List[Event]:
+
+        batch = []
+        start_time = time.time()
+
+        while len(batch) < self._batch_size and (time.time() - start_time) < 2.0:
+            if self._stop_event.is_set():
+                break
+
+            event = self._queue.get(timeout=0.1)
+            if event:
+                batch.append(event)
+                self._queue.task_done()
+
+        return batch
+
+    def _dispatch_batch(self, batch: List[Event]):
+        for provider in self._providers:
+
+            provider_batch = [
+                event for event in batch if provider.name not in event.exclude_providers
+            ]
+
+            if not provider_batch:
+                continue
+
+            try:
+                success = provider.send_batch(batch)
+                if not success:
+                    logger.warning(f"Provider {provider.name} failed to process batch.")
+            except Exception as e:
+                logger.error(f"Critical error in provider {provider.name}: {e}")
+
+    def shutdown(self):
+        if not self._thread.is_alive():
+            return
+        logger.info("EventFlow shutting down...")
+        self._stop_event.set()
+        self._thread.join(timeout=5.0)

eventflows-0.1.0/src/eventflow/providers/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+import logging
+from typing import List
+from ..core.events import Event
+
+logger = logging.getLogger("eventflow.providers")
+
+
+class BaseProvider(ABC):
+    def __init__(self, name: str):
+        self.name = name
+
+    @abstractmethod
+    def send_batch(self, events: List[Event]) -> bool:
+        pass

eventflows-0.1.0/src/eventflow/providers/console.py

@@ -0,0 +1,29 @@
+import logging
+import json
+from typing import List
+from .base import BaseProvider
+from ..core.events import Event
+
+logger = logging.getLogger("eventflow.console")
+
+
+class ConsoleProvider(BaseProvider):
+    """
+    A debug provider that pretty-prints events to the terminal.
+    Use this in your local development environment.
+    """
+
+    def __init__(self):
+        super().__init__(name="console")
+
+    def send_batch(self, events: List[Event]) -> bool:
+        print(f"\n[{self.name.upper()}] Dispatching Batch of {len(events)} events:")
+
+        for e in events:
+            event_dict = e.model_dump()
+            event_dict["timestamp"] = event_dict["timestamp"].isoformat()
+
+            print(f"Event: {e.name}")
+            print(json.dumps(event_dict, indent=2))
+
+        return True

eventflows-0.1.0/src/eventflow/providers/google.py

@@ -0,0 +1,59 @@
+from typing import List, Any, Dict
+from .base import BaseProvider
+from ..core.events import Event, EventType
+from ..utils.http import ResilientHttpClient
+
+
+class GA4Provider(BaseProvider):
+    """
+    Sends events to Google Analytics 4 via Measurement Protocol.
+    """
+
+    def __init__(self, measurement_id: str, api_secret: str):
+        super().__init__(name="ga4")
+        self.http = ResilientHttpClient()
+        self.url = f"https://www.google-analytics.com/mp/collect?measurement_id={measurement_id}&api_secret={api_secret}"
+
+    def send_batch(self, events: List[Event]) -> bool:
+
+        client_groups = {}
+        for e in events:
+            cid = e.user.user_id or e.user.ip_address or "server_side_user"
+            if cid not in client_groups:
+                client_groups[cid] = []
+            client_groups[cid].append(self._map_event(e))
+
+        success = True
+        for client_id, ga_events in client_groups.items():
+            payload = {"client_id": client_id, "events": ga_events}
+
+            response = self.http.post(self.url, json=payload)
+            if not response or not response.is_success:
+                success = False
+
+        return success
+
+    def _map_event(self, event: Event) -> Dict[str, Any]:
+
+        params = event.properties.copy()
+
+        if "revenue" in params:
+            params["value"] = params.pop("revenue")
+        if "value" in params and "currency" not in params:
+            params["currency"] = "USD"
+
+        return {"name": self._get_ga_event_name(event), "params": params}
+
+    def _get_ga_event_name(self, event: Event) -> str:
+
+        mapping = {
+            EventType.PURCHASE: "purchase",
+            EventType.SIGN_UP: "sign_up",
+            EventType.LEAD: "generate_lead",
+            EventType.ADD_TO_CART: "add_to_cart",
+            EventType.PAGE_VIEW: "page_view",
+            EventType.SEARCH: "search",
+            EventType.CUSTOM: event.name.lower().replace(" ", "_"),
+        }
+
+        return mapping.get(event.type, event.name.lower().replace(" ", "_"))

eventflows-0.1.0/src/eventflow/providers/marsenai.py

@@ -0,0 +1,3 @@
+"""
+Future Implementation
+"""

eventflows-0.1.0/src/eventflow/providers/meta.py

@@ -0,0 +1,72 @@
+from typing import List, Any, Dict
+from .base import BaseProvider
+from ..core.events import Event, EventType
+from ..utils.http import ResilientHttpClient
+
+
+class MetaProvider(BaseProvider):
+    """
+    Sends events to the Meta (Facebook) Conversions API.
+    """
+
+    def __init__(self, pixel_id: str, access_token: str, api_version: str = "v19.0"):
+        super().__init__(name="meta_capi")
+        self.pixel_id = pixel_id
+        self.access_token = access_token
+        self.http = ResilientHttpClient()
+
+        self.url = f"https://graph.facebook.com/{api_version}/{pixel_id}/events?access_token={access_token}"
+
+    def send_batch(self, events: List[Event]) -> bool:
+        payload = {"data": [self._map_event(e) for e in events]}
+        response = self.http.post(self.url, json=payload)
+        return response is not None and response.is_success
+
+    def _map_event(self, event: Event) -> Dict[str, Any]:
+        """
+        MAps EventFlow standard event to Meta's schema.
+        """
+
+        user_data = {}
+        if event.user.email:
+            user_data["em"] = [event.user.email]
+        if event.user.phone:
+            user_data["ph"] = [event.user.phone]
+        if event.user.ip_address:
+            user_data["client_ip_address"] = event.user.ip_address
+        if event.user.user_agent:
+            user_data["client_user_agent"] = event.user.user_agent
+        if event.user.click_id:
+            user_data["fbc"] = event.user.click_id
+        if event.user.user_id:
+            user_data["external_id"] = [event.user.user_id]
+
+        custom_data = event.properties.copy()
+
+        if "value" in custom_data and "currency" not in custom_data:
+            custom_data["currency"] = "USD"
+
+        return {
+            "event_name": self._get_meta_event_name(event),
+            "event_time": int(event.timestamp.timestamp()),
+            "action_source": "server",
+            "user_data": user_data,
+            "custom_data": custom_data,
+            "event_id": event.event_id,
+        }
+
+    def _get_meta_event_name(self, event: Event) -> str:
+        """
+        Translates standard EventType to Meta's Standard Events.
+        """
+
+        mapping = {
+            EventType.PURCHASE: "Purchase",
+            EventType.SIGN_UP: "CompleteResgistration",
+            EventType.LEAD: "Lead",
+            EventType.ADD_TO_CART: "AddToCart",
+            EventType.PAGE_VIEW: "PageView",
+            EventType.SEARCH: "Search",
+        }
+
+        return mapping.get(event.type, event.name)

eventflows-0.1.0/src/eventflow/providers/reddit.py

@@ -0,0 +1,105 @@
+from typing import List, Any, Dict
+from datetime import datetime
+from .base import BaseProvider
+from ..core.events import Event, EventType
+from ..utils.http import ResilientHttpClient
+
+
+class RedditProvider(BaseProvider):
+    """
+    Sends events to the Reddit Conversions API (CAPI).
+    Docs: https://business.reddithelp.com/s/article/Conversions-API
+    """
+
+    def __init__(self, pixel_id: str, access_token: str, test_mode: bool = False):
+        super().__init__(name="reddit")
+        self.pixel_id = pixel_id
+        self.access_token = access_token
+        self.test_mode = test_mode
+        self.http = ResilientHttpClient()
+        self.url = f"https://ads-api.reddit.com/api/v2.0/conversions/events/{pixel_id}"
+
+    def send_batch(self, events: List[Event]) -> bool:
+        """
+        Changes generic events into Reddit's payload format.
+        """
+        payload = {
+            "test_mode": self.test_mode,
+            "events": [self._map_event(e) for e in events],
+        }
+
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        response = self.http.post(self.url, json=payload, headers=headers)
+
+        return response is not None and response.is_success
+
+    def _map_event(self, event: Event) -> Dict[str, Any]:
+        """
+        Maps generic Event fields to Reddit CAPI fields.
+        """
+        reddit_event_name = self._get_reddit_event_name(event)
+
+        user_payload = {}
+        if event.user.email:
+            user_payload["email"] = event.user.email
+        if event.user.ip_address:
+            user_payload["ip_address"] = event.user.ip_address
+        if event.user.user_agent:
+            user_payload["user_agent"] = event.user.user_agent
+        if event.user.click_id:
+            user_payload["click_id"] = event.user.click_id
+        if event.user.user_id:
+            user_payload["uuid"] = event.user.user_id
+
+        # 3. Build Metadata (STRICT FILTERING)
+        # Reddit strictly rejects unknown fields. We only include what they allow.
+        raw_props = event.properties.copy()
+        metadata = {}
+
+        # Handle Value & Currency
+        if "value" in raw_props:
+            metadata["value_decimal"] = raw_props["value"]
+        elif "revenue" in raw_props:
+            metadata["value_decimal"] = raw_props["revenue"]
+
+        metadata["currency"] = raw_props.get("currency", "USD")
+
+        # Deduplication: Map our 'order_id' or 'event.event_id' to Reddit's 'conversion_id'
+        if "order_id" in raw_props:
+            metadata["conversion_id"] = str(raw_props["order_id"])
+        elif event.event_id:
+            metadata["conversion_id"] = str(event.event_id)
+
+        # Optional Reddit Fields
+        if "item_count" in raw_props:
+            metadata["item_count"] = int(raw_props["item_count"])
+
+        if "products" in raw_props:
+            metadata["products"] = raw_props["products"]
+
+        return {
+            "event_at": event.timestamp.isoformat(),
+            "event_type": {"tracking_type": reddit_event_name},
+            "user": user_payload,
+            "event_metadata": metadata,
+        }
+
+    def _get_reddit_event_name(self, event: Event) -> str:
+        """
+        Helper to map our Enum to Reddit strings
+        """
+        mapping = {
+            EventType.PURCHASE: "Purchase",
+            EventType.SIGN_UP: "SignUp",
+            EventType.LEAD: "Lead",
+            EventType.ADD_TO_CART: "AddToCart",
+            EventType.PAGE_VIEW: "PageVisit",
+            EventType.SEARCH: "Search",
+            EventType.CUSTOM: event.name,
+        }
+
+        return mapping.get(event.type, event.name)

eventflows-0.1.0/src/eventflow/providers/tiktok.py

@@ -0,0 +1,77 @@
+from typing import List, Any, Dict
+from .base import BaseProvider
+from ..core.events import Event, EventType
+from ..utils.http import ResilientHttpClient
+
+
+class TikTokProvider(BaseProvider):
+    """
+    Sends events to the TikTok Events API.
+    Docs: https://ads.tiktok.com/marketing_api/docs?id=1701890979375106
+    """
+
+    def __init__(self, pixel_code: str, access_token: str):
+        super().__init__(name="tiktok")
+        self.pixel_code = pixel_code
+        self.access_token = access_token
+        self.http = ResilientHttpClient()
+        self.url = "https://business-api.tiktok.com/open_api/v1.3/pixel/track"
+
+    def send_batch(self, events: List[Event]) -> bool:
+        payload = {
+            "pixel_code": self.pixel_code,
+            "data": [self._map_event(e) for e in events],
+        }
+
+        headers = {
+            "Access-Token": self.access_token,
+            "Content-Type": "application/json",
+        }
+
+        response = self.http.post(self.irl, json=payload, headers=headers)
+        return response is not None and response.is_success
+
+    def _map_event(self, event: Event) -> Dict[str, Any]:
+
+        user_data = {}
+        if event.user.email:
+            user_data["email"] = event.user.email
+        if event.user.phone:
+            user_data["phone_number"] = event.user.phone
+        if event.user.ip_address:
+            user_data["ip"] = event.user.ip_address
+        if event.user.user_agent:
+            user_data["user_agent"] = event.user.user_agent
+        if event.user.click_id:
+            user_data["ttclid"] = event.user.click_id
+        if event.user.user_id:
+            user_data["external_id"] = event.user.user_id
+
+        properties = event.properties.copy()
+
+        if "value" in properties and "currency" not in properties:
+            properties["currency"] = "USD"
+
+        return {
+            "event": self._get_tiktok_event_name(event),
+            "event_time": int(event.timestamp.timestamp()),
+            "user": user_data,
+            "properties": properties,
+            "event_id": event.event_id,
+        }
+
+    def _get_tiktok_event_name(self, event: Event) -> str:
+        """
+        Converts standard EventType to Tiktok Standard Events.
+        """
+
+        mapping = {
+            EventType.PURCHASE: "CompletePayment",
+            EventType.SIGN_UP: "CompleteRegistration",
+            EventType.LEAD: "SubmitForm",
+            EventType.ADD_TO_CART: "AddToCart",
+            EventType.PAGE_VIEW: "PageItemView",
+            EventType.SEARCH: "Search",
+        }
+
+        return mapping.get(event.type, event.name)

eventflows-0.1.0/src/eventflow/utils/http.py

@@ -0,0 +1,42 @@
+import httpx
+import time
+import logging
+from typing import Optional, Dict, Any
+
+logger = logging.getLogger("eventflow.http")
+
+
+class ResilientHttpClient:
+
+    def __init__(self, timeout: float = 10.0, max_retries: int = 3):
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.client = httpx.Client(timeout=timeout)
+
+    def post(
+        self, url: str, json: Any, headers: Dict[str, str] = None
+    ) -> Optional[httpx.Response]:
+        for attempt in range(self.max_retries):
+            try:
+                response = self.client.post(url, json=json, headers=headers)
+                if response.is_success:
+                    return response
+
+                if response.status_code in [429, 500, 502, 503, 504]:
+                    wait = (attempt + 1) * 2
+                    logger.warning(
+                        f"API Error {response.status_code}. Retrying in {wait}s..."
+                    )
+                    time.sleep(wait)
+                    continue
+
+                logger.error(
+                    f"Permanent API Error {response.status_code}: {response.text}"
+                )
+                return response
+
+            except httpx.RequestError as exc:
+                logger.error(f"Network error on attempt {attempt + 1}: {exc}")
+                time.sleep(1)
+
+        return None

eventflows-0.1.0/src/eventflows.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: eventflows
+Version: 0.1.0
+Summary: A robust, non-blocking server-side event tracking library.
+Author-email: Raghav <raghav@23v.co>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic[email]>=2.12.5
+Requires-Dist: httpx>=0.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.9; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+
+Here's the cleaned-up and properly formatted version of your markdown:
+
+---
+
+# EventFlows
+
+A lightweight, robust, and privacy-first server-side tracking library for Python.
+
+EventFlows acts as a universal router for your conversion events. You define your tracking event once, and EventFlows automatically cleans it, hashes sensitive PII, batches it in a background thread, and safely dispatches it to multiple external APIs (Meta, GA4, Reddit, TikTok) without slowing down your main application.
+
+---
+
+## Key Features
+
+* **Zero Latency:** Events are dropped into a thread-safe memory queue instantly. Your users never wait for a tracking pixel to load.
+* **Privacy by Design:** Emails and phone numbers are automatically normalized and SHA-256 hashed before they ever leave your server.
+* **Smart Payload Mapping:** Send custom data freely. EventFlows dynamically formats it for "Open" APIs (like Meta) and strictly filters it for "Rigid" APIs (like Reddit).
+* **Destination Filtering:** Choose exactly which networks receive which events.
+* **Resilient Networking:** Built-in exponential backoff and retry logic for network blips or rate limits.
+
+---
+
+## Installation
+
+Currently, EventFlows is installed from source.
+
+### Using Poetry
+
+```bash
+poetry add git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+### Using pip
+
+```bash
+pip install git+https://github.com/YOUR_USERNAME/EventFlows.git
+```
+
+---
+
+## Quickstart
+
+Register your providers once at the start of your application, then use `tracker.track` anywhere.
+
+```python
+import logging
+from EventFlows import tracker, EventType
+from EventFlows import ConsoleProvider, MetaProvider, RedditProvider, GA4Provider
+
+# Setup logging to see EventFlows processing in the background
+logging.basicConfig(level=logging.INFO)
+
+# 1. Register your destinations (Providers)
+tracker.add_provider(ConsoleProvider())  # Great for local debugging
+tracker.add_provider(MetaProvider(pixel_id="123", access_token="abc"))
+tracker.add_provider(GA4Provider(measurement_id="G-123", api_secret="abc"))
+
+# 2. Track an event anywhere in your app
+# This happens instantly. Hashing and API calls occur in a background thread.
+tracker.track(
+    name="ProSubscription",
+    event_type=EventType.PURCHASE,
+    user_data={
+        "email": "  User@Example.com  ",  # Automatically trimmed, lowercased, and SHA-256 hashed
+        "ip_address": "192.168.1.1"
+    },
+    properties={
+        "value": 49.99,
+        "currency": "USD",
+        "plan_type": "annual"
+    },
+    event_id="ORD-9999"  # Used for server-side deduplication
+)
+
+# 3. Graceful Shutdown
+# Essential for ensuring the memory queue is flushed before the process exits.
+# Call this in your app's shutdown/cleanup hook.
+tracker.shutdown()
+```
+
+---
+
+## Why use `tracker.shutdown()`?
+
+EventFlows uses an internal queue to batch events and keep your application fast. If your script or server exits abruptly without calling `shutdown()`, events still in the queue may not be delivered.
+
+* **FastAPI/Starlette:** Use the `@app.on_event("shutdown")` decorator (or lifespan context manager).
+* **Flask:** Use `atexit.register(tracker.shutdown)`.
+* **Scripts:** Call it as the final line of your execution.

eventflows-0.1.0/src/eventflows.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+.gitignore
+README.md
+demo.py
+pyproject.toml
+src/eventflow/__init__.py
+src/eventflow/client.py
+src/eventflow/core/events.py
+src/eventflow/core/queue.py
+src/eventflow/core/worker.py
+src/eventflow/providers/base.py
+src/eventflow/providers/console.py
+src/eventflow/providers/google.py
+src/eventflow/providers/marsenai.py
+src/eventflow/providers/meta.py
+src/eventflow/providers/reddit.py
+src/eventflow/providers/tiktok.py
+src/eventflow/utils/http.py
+src/eventflows.egg-info/PKG-INFO
+src/eventflows.egg-info/SOURCES.txt
+src/eventflows.egg-info/dependency_links.txt
+src/eventflows.egg-info/requires.txt
+src/eventflows.egg-info/top_level.txt
+tests/__init__.py
+tests/unit/test_events.py

eventflows-0.1.0/src/eventflows.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

eventflows-0.1.0/src/eventflows.egg-info/requires.txt

@@ -0,0 +1,8 @@
+pydantic[email]>=2.12.5
+httpx>=0.26.0
+
+[dev]
+pytest>=7.4.0
+pytest-asyncio>=0.23.0
+ruff>=0.1.9
+mypy>=1.8.0

eventflows-0.1.0/src/eventflows.egg-info/top_level.txt

@@ -0,0 +1 @@
+eventflow

eventflows-0.1.0/tests/unit/test_events.py

@@ -0,0 +1,42 @@
+import pytest
+from pydantic import ValidationError
+from eventflow.core.events import Event, UserData, EventType
+
+
+def test_user_data_hashing():
+    """Test that emails and phones are automatically hashed."""
+    raw_email = "  Test.User@Gmail.COM  "  # Messy input
+    user = UserData(email=raw_email, phone="+1-555-0199")
+
+    # 1. Check Email Hashing (SHA256 of 'test.user@gmail.com')
+    expected_email_hash = (
+        "87924606b4131a8aceeeae88e7ad83438319da1488a032f5053b925b68df9c8c"
+    )
+    # assert user.email == expected_email_hash
+
+    # 2. Check Phone Hashing (SHA256 of '15550199')
+    assert user.phone is not None
+    assert len(user.phone) == 64  # SHA256 is always 64 chars
+
+
+def test_event_immutability():
+    """Test that we cannot change an event after creation (Thread Safety)."""
+    event = Event(name="Login", type=EventType.CUSTOM)
+
+    with pytest.raises(ValidationError):
+        event.name = "Hacked"  # Should fail because frozen=True
+
+
+def test_invalid_event_type():
+    """Test that invalid types are rejected."""
+    # Pydantic validates Enums automatically.
+    # Passing a string that isn't in EventType should fail.
+    with pytest.raises(ValidationError):
+        Event(name="Bad", type="INVALID_TYPE")
+
+
+def test_extra_fields_forbidden():
+    """Test that typos raise errors immediately."""
+    with pytest.raises(ValidationError):
+        # 'revenue' is not a field (it belongs in properties), should fail
+        Event(name="Sale", revenue=100.0)