metricsfirst 0.1.7__py3-none-any.whl

metricsfirst/__init__.py

@@ -0,0 +1,30 @@
+"""
+MetricsFirst SDK for Python
+Track analytics for your Telegram bots
+"""
+
+from .client import MetricsFirst
+from .async_client import AsyncMetricsFirst
+from .types import (
+    ServiceEventData,
+    ErrorEventData,
+    ErrorSeverity,
+    PurchaseEventData,
+    PurchaseStatus,
+    RecurringChargeEventData,
+    UserIdentifyData,
+)
+
+__version__ = "0.1.1"
+__all__ = [
+    "MetricsFirst",
+    "AsyncMetricsFirst",
+    "ServiceEventData",
+    "ErrorEventData",
+    "ErrorSeverity",
+    "PurchaseEventData",
+    "PurchaseStatus",
+    "RecurringChargeEventData",
+    "UserIdentifyData",
+]
+

metricsfirst/async_client.py

@@ -0,0 +1,365 @@
+"""
+Asynchronous MetricsFirst client
+"""
+
+import asyncio
+import json
+import logging
+from dataclasses import asdict
+from typing import Optional, List, Dict, Any
+
+try:
+    import aiohttp
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False
+
+from .types import (
+    ServiceEventData,
+    ErrorEventData,
+    PurchaseEventData,
+    PurchaseStatus,
+    RecurringChargeEventData,
+    UserIdentifyData,
+)
+
+logger = logging.getLogger("metricsfirst")
+
+
+class AsyncMetricsFirst:
+    """
+    Asynchronous MetricsFirst SDK client.
+    
+    Note: Commands and interactions are tracked automatically.
+    Use this SDK to track custom events like services, purchases, and errors.
+    
+    Usage:
+        mf = AsyncMetricsFirst(bot_id="your_bot_id", api_key="your_api_key")
+        await mf.start()
+        mf.track_service(ServiceEventData(user_id=123, service_name="generation"))
+        await mf.shutdown()  # Call on exit to flush remaining events
+    """
+    
+    DEFAULT_API_URL = "https://metricsfirst.io/api"
+    
+    def __init__(
+        self,
+        bot_id: str,
+        api_key: str,
+        api_url: Optional[str] = None,
+        batch_events: bool = True,
+        batch_size: int = 10,
+        batch_interval: float = 5.0,
+        debug: bool = False,
+        timeout: float = 10.0,
+    ):
+        """
+        Initialize the AsyncMetricsFirst client.
+        
+        Args:
+            bot_id: Your bot's unique identifier
+            api_key: Your API key from MetricsFirst dashboard
+            api_url: Custom API URL (optional)
+            batch_events: Whether to batch events before sending
+            batch_size: Number of events per batch
+            batch_interval: Seconds between batch flushes
+            debug: Enable debug logging
+            timeout: HTTP request timeout in seconds
+        """
+        if not HAS_AIOHTTP:
+            raise ImportError(
+                "aiohttp is required for AsyncMetricsFirst. "
+                "Install with: pip install metricsfirst[async]"
+            )
+        
+        self.bot_id = bot_id
+        self.api_key = api_key
+        self.api_url = (api_url or self.DEFAULT_API_URL).rstrip("/")
+        self.batch_events = batch_events
+        self.batch_size = batch_size
+        self.batch_interval = batch_interval
+        self.timeout = aiohttp.ClientTimeout(total=timeout)
+        
+        if debug:
+            logging.basicConfig(level=logging.DEBUG)
+            logger.setLevel(logging.DEBUG)
+        
+        # Max 1000 events in queue to prevent memory issues
+        self._queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._worker_task: Optional[asyncio.Task] = None
+        self._shutdown_event = asyncio.Event()
+    
+    async def start(self):
+        """Start the client and background worker"""
+        self._session = aiohttp.ClientSession(timeout=self.timeout)
+        self._shutdown_event.clear()
+        
+        if self.batch_events:
+            self._worker_task = asyncio.create_task(self._worker())
+        
+        logger.debug("AsyncMetricsFirst client started")
+    
+    async def _worker(self):
+        """Background worker that flushes events periodically"""
+        events: List[Dict[str, Any]] = []
+        
+        while not self._shutdown_event.is_set():
+            try:
+                # Try to get an event with timeout
+                event = await asyncio.wait_for(
+                    self._queue.get(),
+                    timeout=self.batch_interval
+                )
+                events.append(event)
+                
+                # Flush if batch is full
+                if len(events) >= self.batch_size:
+                    await self._flush_events(events)
+                    events = []
+                    
+            except asyncio.TimeoutError:
+                # Timeout - flush what we have
+                if events:
+                    await self._flush_events(events)
+                    events = []
+            except asyncio.CancelledError:
+                break
+        
+        # Flush remaining events on shutdown
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except asyncio.QueueEmpty:
+                break
+        
+        if events:
+            await self._flush_events(events)
+    
+    async def _flush_events(self, events: List[Dict[str, Any]]):
+        """Send a batch of events to the API"""
+        if not events:
+            return
+        
+        try:
+            tasks = [
+                self._send_event(event["type"], event["data"])
+                for event in events
+            ]
+            await asyncio.gather(*tasks, return_exceptions=True)
+        except Exception as e:
+            logger.error(f"Failed to flush events: {e}")
+    
+    async def _send_event(self, event_type: str, data: Dict[str, Any]):
+        """Send a single event to the API"""
+        if not self._session:
+            logger.error("Client not started. Call start() first.")
+            return
+        
+        payload = {
+            "botId": self.bot_id,
+            "type": event_type,
+            "data": data,
+        }
+        
+        # URL: base/analytics/track (base already includes /api if provided)
+        url = f"{self.api_url}/analytics/track"
+        
+        try:
+            async with self._session.post(
+                url,
+                json=payload,
+                headers={"X-API-Key": self.api_key},
+            ) as response:
+                if response.status != 200:
+                    text = await response.text()
+                    try:
+                        error_data = json.loads(text)
+                        error_message = error_data.get("error", text[:200])
+                    except json.JSONDecodeError:
+                        error_message = text[:200]
+                    logger.warning(f"API returned status {response.status} for {url}: {error_message}")
+                else:
+                    logger.debug(f"Event sent: {event_type}")
+                    
+        except aiohttp.ClientError as e:
+            logger.error(f"HTTP error sending event: {e}")
+        except Exception as e:
+            logger.error(f"Error sending event: {e}")
+    
+    def _track(self, event_type: str, data: Dict[str, Any]):
+        """Queue or send an event (non-blocking, fire-and-forget)"""
+        if self.batch_events:
+            # Non-blocking put to queue - background task will handle sending
+            try:
+                self._queue.put_nowait({"type": event_type, "data": data})
+            except asyncio.QueueFull:
+                logger.warning("Event queue full, dropping event")
+        else:
+            # Fire and forget - create task without awaiting
+            asyncio.create_task(self._send_event(event_type, data))
+    
+    def _clean_dict(self, d: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove None values and convert enums"""
+        result = {}
+        for k, v in d.items():
+            if v is None:
+                continue
+            if hasattr(v, "value"):  # Enum
+                result[k] = v.value
+            elif isinstance(v, dict):
+                result[k] = self._clean_dict(v)
+            else:
+                result[k] = v
+        return result
+    
+    # ==========================================
+    # Tracking Methods (fire-and-forget, non-blocking)
+    # Note: Commands/interactions are tracked automatically
+    # ==========================================
+    
+    def track(
+        self,
+        user_id: int,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Track a custom event with dynamic properties.
+        
+        Args:
+            user_id: User ID (Telegram user ID)
+            event_name: Name of the event (e.g., 'STORY_RESPONSE', 'BUTTON_CLICK')
+            properties: Dictionary of event properties (any key-value pairs)
+        
+        Example:
+            mf.track(123456, 'STORY_RESPONSE', {
+                'target': 'username123',
+                'url': 'https://example.com/story',
+                'response_time_ms': 150,
+                'success': True
+            })
+        """
+        data = {
+            "eventName": event_name,
+            "properties": properties or {},
+            "userId": user_id,
+            "lib": "python",
+            "libVersion": "1.0.0",
+        }
+        
+        self._track("custom", data)
+    
+    def track_service(self, data: ServiceEventData):
+        """Track a service provided (fire-and-forget)"""
+        self._track("service_provided", self._clean_dict(asdict(data)))
+    
+    def track_error(self, data: ErrorEventData):
+        """Track an error (fire-and-forget)"""
+        self._track("error", self._clean_dict(asdict(data)))
+    
+    def track_error_from_exception(
+        self,
+        exception: Exception,
+        user_id: Optional[int] = None,
+        severity: str = "error",
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Track an error from an exception (fire-and-forget)"""
+        import traceback
+        
+        err_data = ErrorEventData(
+            error_type=type(exception).__name__,
+            error_message=str(exception),
+            user_id=user_id,
+            error_stack=traceback.format_exc(),
+            severity=severity,
+            context=context or {},
+        )
+        self.track_error(err_data)
+    
+    def track_purchase_initiated(self, data: PurchaseEventData):
+        """Track a purchase initiation (fire-and-forget)"""
+        data.status = PurchaseStatus.INITIATED
+        self._track("purchase_initiated", self._clean_dict(asdict(data)))
+    
+    def track_purchase_completed(self, data: PurchaseEventData):
+        """Track a completed purchase (fire-and-forget)"""
+        data.status = PurchaseStatus.COMPLETED
+        self._track("purchase_completed", self._clean_dict(asdict(data)))
+    
+    def track_purchase_error(self, data: PurchaseEventData):
+        """Track a failed purchase (fire-and-forget)"""
+        data.status = PurchaseStatus.FAILED
+        self._track("purchase_error", self._clean_dict(asdict(data)))
+    
+    def track_recurring_charge_success(self, data: RecurringChargeEventData):
+        """Track a successful recurring charge (fire-and-forget)"""
+        data.is_success = True
+        self._track("recurring_charge_success", self._clean_dict(asdict(data)))
+    
+    def track_recurring_charge_failed(self, data: RecurringChargeEventData):
+        """Track a failed recurring charge (fire-and-forget)"""
+        data.is_success = False
+        self._track("recurring_charge_failed", self._clean_dict(asdict(data)))
+    
+    async def identify(self, data: UserIdentifyData):
+        """Identify a user with properties"""
+        if not self._session:
+            logger.error("Client not started. Call start() first.")
+            return
+        
+        payload = self._clean_dict(asdict(data))
+        
+        try:
+            async with self._session.post(
+                f"{self.api_url}/api/users/identify",
+                json={"botId": self.bot_id, **payload},
+                headers={"X-API-Key": self.api_key},
+            ) as response:
+                if response.status != 200:
+                    logger.warning(f"Identify returned status {response.status}")
+                    
+        except Exception as e:
+            logger.error(f"Error identifying user: {e}")
+    
+    async def flush(self):
+        """Manually flush all pending events"""
+        if not self.batch_events:
+            return
+        
+        events = []
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except asyncio.QueueEmpty:
+                break
+        
+        await self._flush_events(events)
+    
+    async def shutdown(self):
+        """Shutdown the client and flush remaining events"""
+        self._shutdown_event.set()
+        
+        if self._worker_task:
+            self._worker_task.cancel()
+            try:
+                await self._worker_task
+            except asyncio.CancelledError:
+                pass
+        
+        # Flush any remaining events
+        await self.flush()
+        
+        if self._session:
+            await self._session.close()
+        
+        logger.debug("AsyncMetricsFirst client shutdown complete")
+    
+    async def __aenter__(self):
+        await self.start()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.shutdown()
+

metricsfirst/client.py

@@ -0,0 +1,353 @@
+"""
+Synchronous MetricsFirst client
+"""
+
+import json
+import logging
+import threading
+import time
+from dataclasses import asdict
+from queue import Queue, Empty
+from typing import Optional, List, Dict, Any
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+from .types import (
+    ServiceEventData,
+    ErrorEventData,
+    PurchaseEventData,
+    PurchaseStatus,
+    RecurringChargeEventData,
+    UserIdentifyData,
+)
+
+logger = logging.getLogger("metricsfirst")
+
+
+class MetricsFirst:
+    """
+    Synchronous MetricsFirst SDK client.
+    
+    Note: Commands and interactions are tracked automatically.
+    Use this SDK to track custom events like services, purchases, and errors.
+    
+    Usage:
+        mf = MetricsFirst(bot_id="your_bot_id", api_key="your_api_key")
+        mf.track_service(ServiceEventData(user_id=123, service_name="generation"))
+        mf.shutdown()  # Call on exit to flush remaining events
+    """
+    
+    DEFAULT_API_URL = "https://metricsfirst.io/api"
+    
+    def __init__(
+        self,
+        bot_id: str,
+        api_key: str,
+        api_url: Optional[str] = None,
+        batch_events: bool = True,
+        batch_size: int = 10,
+        batch_interval: float = 5.0,
+        debug: bool = False,
+        timeout: float = 10.0,
+    ):
+        """
+        Initialize the MetricsFirst client.
+        
+        Args:
+            bot_id: Your bot's unique identifier
+            api_key: Your API key from MetricsFirst dashboard
+            api_url: Custom API URL (optional)
+            batch_events: Whether to batch events before sending
+            batch_size: Number of events per batch
+            batch_interval: Seconds between batch flushes
+            debug: Enable debug logging
+            timeout: HTTP request timeout in seconds
+        """
+        self.bot_id = bot_id
+        self.api_key = api_key
+        self.api_url = (api_url or self.DEFAULT_API_URL).rstrip("/")
+        self.batch_events = batch_events
+        self.batch_size = batch_size
+        self.batch_interval = batch_interval
+        self.timeout = timeout
+        
+        if debug:
+            logging.basicConfig(level=logging.DEBUG)
+            logger.setLevel(logging.DEBUG)
+        
+        # Max 1000 events in queue to prevent memory issues
+        self._queue: Queue = Queue(maxsize=1000)
+        self._shutdown = threading.Event()
+        self._worker_thread: Optional[threading.Thread] = None
+        
+        if batch_events:
+            self._start_worker()
+    
+    def _start_worker(self):
+        """Start the background worker thread for batching"""
+        self._worker_thread = threading.Thread(target=self._worker, daemon=True)
+        self._worker_thread.start()
+    
+    def _worker(self):
+        """Background worker that flushes events periodically"""
+        events: List[Dict[str, Any]] = []
+        last_flush = time.time()
+        
+        while not self._shutdown.is_set():
+            try:
+                # Try to get an event with timeout
+                event = self._queue.get(timeout=0.1)
+                events.append(event)
+                
+                # Flush if batch is full
+                if len(events) >= self.batch_size:
+                    self._flush_events(events)
+                    events = []
+                    last_flush = time.time()
+            except Empty:
+                pass
+            
+            # Flush if interval has passed
+            if events and (time.time() - last_flush) >= self.batch_interval:
+                self._flush_events(events)
+                events = []
+                last_flush = time.time()
+        
+        # Flush remaining events on shutdown
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except Empty:
+                break
+        
+        if events:
+            self._flush_events(events)
+    
+    def _flush_events(self, events: List[Dict[str, Any]]):
+        """Send a batch of events to the API"""
+        if not events:
+            return
+        
+        try:
+            for event in events:
+                self._send_event(event["type"], event["data"])
+        except Exception as e:
+            logger.error(f"Failed to flush events: {e}")
+    
+    def _send_event(self, event_type: str, data: Dict[str, Any]):
+        """Send a single event to the API"""
+        payload = {
+            "botId": self.bot_id,
+            "type": event_type,
+            "data": data,
+        }
+        
+        # URL: base/analytics/track (base already includes /api if provided)
+        url = f"{self.api_url}/analytics/track"
+        
+        try:
+            request = Request(
+                url,
+                data=json.dumps(payload).encode("utf-8"),
+                headers={
+                    "Content-Type": "application/json",
+                    "X-API-Key": self.api_key,
+                },
+                method="POST",
+            )
+            
+            with urlopen(request, timeout=self.timeout) as response:
+                if response.status != 200:
+                    response_body = response.read().decode("utf-8")
+                    logger.warning(f"API returned status {response.status} for {url}: {response_body}")
+                else:
+                    logger.debug(f"Event sent: {event_type}")
+                    
+        except HTTPError as e:
+            # Read error response body to get detailed error message
+            try:
+                error_body = e.read().decode("utf-8")
+                error_data = json.loads(error_body)
+                error_message = error_data.get("error", e.reason)
+            except Exception:
+                error_message = e.reason
+            logger.warning(f"API returned status {e.code} for {url}: {error_message}")
+        except URLError as e:
+            logger.error(f"URL error sending event: {e.reason}")
+        except Exception as e:
+            logger.error(f"Error sending event: {e}")
+    
+    def _track(self, event_type: str, data: Dict[str, Any]):
+        """Queue or send an event (non-blocking, fire-and-forget)"""
+        if self.batch_events:
+            # Non-blocking put to queue - background thread will handle sending
+            try:
+                self._queue.put_nowait({"type": event_type, "data": data})
+            except Exception:
+                logger.warning("Event queue full, dropping event")
+        else:
+            # Send in background thread to avoid blocking
+            threading.Thread(
+                target=self._send_event,
+                args=(event_type, data),
+                daemon=True
+            ).start()
+    
+    def _clean_dict(self, d: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove None values and convert enums"""
+        result = {}
+        for k, v in d.items():
+            if v is None:
+                continue
+            if hasattr(v, "value"):  # Enum
+                result[k] = v.value
+            elif isinstance(v, dict):
+                result[k] = self._clean_dict(v)
+            else:
+                result[k] = v
+        return result
+    
+    # ==========================================
+    # Tracking Methods (fire-and-forget, non-blocking)
+    # Note: Commands/interactions are tracked automatically
+    # ==========================================
+    
+    def track(
+        self,
+        user_id: int,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Track a custom event with dynamic properties.
+        
+        Args:
+            user_id: User ID (Telegram user ID)
+            event_name: Name of the event (e.g., 'STORY_RESPONSE', 'BUTTON_CLICK')
+            properties: Dictionary of event properties (any key-value pairs)
+        
+        Example:
+            mf.track(123456, 'STORY_RESPONSE', {
+                'target': 'username123',
+                'url': 'https://example.com/story',
+                'response_time_ms': 150,
+                'success': True
+            })
+        """
+        data = {
+            "eventName": event_name,
+            "properties": properties or {},
+            "userId": user_id,
+            "lib": "python",
+            "libVersion": "1.0.0",
+        }
+        
+        self._track("custom", data)
+    
+    def track_service(self, data: ServiceEventData):
+        """Track a service provided"""
+        self._track("service_provided", self._clean_dict(asdict(data)))
+    
+    def track_error(self, data: ErrorEventData):
+        """Track an error"""
+        self._track("error", self._clean_dict(asdict(data)))
+    
+    def track_error_from_exception(
+        self,
+        exception: Exception,
+        user_id: Optional[int] = None,
+        severity: str = "error",
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Track an error from an exception"""
+        import traceback
+        
+        data = ErrorEventData(
+            error_type=type(exception).__name__,
+            error_message=str(exception),
+            user_id=user_id,
+            error_stack=traceback.format_exc(),
+            severity=severity,
+            context=context or {},
+        )
+        self.track_error(data)
+    
+    def track_purchase_initiated(self, data: PurchaseEventData):
+        """Track a purchase initiation"""
+        data.status = PurchaseStatus.INITIATED
+        self._track("purchase_initiated", self._clean_dict(asdict(data)))
+    
+    def track_purchase_completed(self, data: PurchaseEventData):
+        """Track a completed purchase"""
+        data.status = PurchaseStatus.COMPLETED
+        self._track("purchase_completed", self._clean_dict(asdict(data)))
+    
+    def track_purchase_error(self, data: PurchaseEventData):
+        """Track a failed purchase"""
+        data.status = PurchaseStatus.FAILED
+        self._track("purchase_error", self._clean_dict(asdict(data)))
+    
+    def track_recurring_charge_success(self, data: RecurringChargeEventData):
+        """Track a successful recurring charge"""
+        data.is_success = True
+        self._track("recurring_charge_success", self._clean_dict(asdict(data)))
+    
+    def track_recurring_charge_failed(self, data: RecurringChargeEventData):
+        """Track a failed recurring charge"""
+        data.is_success = False
+        self._track("recurring_charge_failed", self._clean_dict(asdict(data)))
+    
+    def identify(self, data: UserIdentifyData):
+        """Identify a user with properties"""
+        payload = self._clean_dict(asdict(data))
+        
+        try:
+            request = Request(
+                f"{self.api_url}/api/users/identify",
+                data=json.dumps({
+                    "botId": self.bot_id,
+                    **payload,
+                }).encode("utf-8"),
+                headers={
+                    "Content-Type": "application/json",
+                    "X-API-Key": self.api_key,
+                },
+                method="POST",
+            )
+            
+            with urlopen(request, timeout=self.timeout) as response:
+                if response.status != 200:
+                    logger.warning(f"Identify returned status {response.status}")
+                    
+        except Exception as e:
+            logger.error(f"Error identifying user: {e}")
+    
+    def flush(self):
+        """Manually flush all pending events"""
+        if not self.batch_events:
+            return
+        
+        events = []
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except Empty:
+                break
+        
+        self._flush_events(events)
+    
+    def shutdown(self):
+        """Shutdown the client and flush remaining events"""
+        self._shutdown.set()
+        
+        if self._worker_thread and self._worker_thread.is_alive():
+            self._worker_thread.join(timeout=5.0)
+        
+        logger.debug("MetricsFirst client shutdown complete")
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.shutdown()
+

metricsfirst/types.py

@@ -0,0 +1,131 @@
+"""
+Type definitions for MetricsFirst SDK
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Dict, Any
+
+
+class InteractionType(str, Enum):
+    MESSAGE = "message"
+    CALLBACK_QUERY = "callback_query"
+    INLINE_QUERY = "inline_query"
+    COMMAND = "command"
+    PHOTO = "photo"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    VOICE = "voice"
+    STICKER = "sticker"
+    OTHER = "other"
+
+
+class ErrorSeverity(str, Enum):
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+class PurchaseStatus(str, Enum):
+    INITIATED = "initiated"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    REFUNDED = "refunded"
+
+
+@dataclass
+class CommandEventData:
+    """Data for tracking bot commands"""
+    user_id: int
+    command: str
+    command_args: Optional[str] = None
+    response_time_ms: Optional[int] = None
+    is_success: bool = True
+    error_message: Optional[str] = None
+
+
+@dataclass
+class InteractionEventData:
+    """Data for tracking user interactions"""
+    user_id: int
+    interaction_type: InteractionType = InteractionType.MESSAGE
+    content_preview: Optional[str] = None
+    callback_data: Optional[str] = None
+    response_time_ms: Optional[int] = None
+
+
+@dataclass
+class ServiceEventData:
+    """Data for tracking services provided"""
+    user_id: int
+    service_name: str
+    service_type: Optional[str] = None
+    is_free: bool = True
+    price: float = 0.0
+    currency: str = "USD"
+    duration_ms: Optional[int] = None
+    is_success: bool = True
+    error_message: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ErrorEventData:
+    """Data for tracking errors"""
+    error_type: str
+    error_message: str
+    user_id: Optional[int] = None
+    error_stack: Optional[str] = None
+    error_code: Optional[str] = None
+    severity: ErrorSeverity = ErrorSeverity.ERROR
+    context: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PurchaseEventData:
+    """Data for tracking purchases"""
+    user_id: int
+    purchase_id: str
+    price: float
+    status: PurchaseStatus = PurchaseStatus.INITIATED
+    tariff_id: Optional[str] = None
+    tariff_name: Optional[str] = None
+    currency: str = "USD"
+    is_recurrent: bool = False
+    recurrence_period: Optional[str] = None  # "daily", "weekly", "monthly", "yearly"
+    payment_method: Optional[str] = None
+    payment_provider: Optional[str] = None
+    discount_percent: float = 0.0
+    coupon_code: Optional[str] = None
+    error_message: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RecurringChargeEventData:
+    """Data for tracking recurring subscription charges"""
+    user_id: int
+    subscription_id: str
+    amount: float
+    is_success: bool = True
+    currency: str = "USD"
+    payment_method: Optional[str] = None
+    charge_attempt: int = 1
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    next_retry_at: Optional[str] = None
+
+
+@dataclass
+class UserIdentifyData:
+    """Data for identifying users"""
+    user_id: int
+    username: Optional[str] = None
+    first_name: Optional[str] = None
+    last_name: Optional[str] = None
+    language_code: Optional[str] = None
+    is_premium: bool = False
+    properties: Dict[str, Any] = field(default_factory=dict)
+

metricsfirst-0.1.7.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: metricsfirst
+Version: 0.1.7
+Summary: MetricsFirst SDK for Python - Analytics for Telegram bots
+Project-URL: Homepage, https://metricsfirst.com
+Project-URL: Documentation, https://docs.metricsfirst.com/python
+Project-URL: Repository, https://github.com/metricsfirst/metricsfirst-python
+Project-URL: Changelog, https://github.com/metricsfirst/metricsfirst-python/blob/main/CHANGELOG.md
+Author-email: MetricsFirst <support@metricsfirst.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,bot,metrics,metricsfirst,telegram,tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.8.0; extra == 'dev'
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MetricsFirst Python SDK
+
+Official Python SDK for [MetricsFirst](https://metricsfirst.com) - Analytics for Telegram bots.
+
+> **Note:** Commands and interactions are tracked automatically when you add your bot to MetricsFirst. This SDK is for tracking custom events like services, purchases, and errors.
+
+## Installation
+
+```bash
+# Basic installation (sync only)
+pip install metricsfirst
+
+# With async support
+pip install metricsfirst[async]
+```
+
+## Features
+
+- **Fire-and-forget**: All tracking calls are non-blocking and don't add latency
+- **Background sending**: Events are sent in a separate thread (sync) or task (async)
+- **Error resilience**: Errors are logged, never thrown to your code
+- **Memory safe**: Queue is limited to 1000 events to prevent memory issues
+- **Custom Events**: Track any event with dynamic properties (Mixpanel-style)
+
+## Quick Start
+
+### Custom Events (Mixpanel-style)
+
+Track any event with dynamic properties:
+
+```python
+from metricsfirst import MetricsFirst
+
+mf = MetricsFirst(
+    bot_id="your_bot_id",
+    api_key="your_api_key",
+)
+
+# Track custom events with any properties
+mf.track(123456789, 'STORY_RESPONSE', {
+    'target': 'username123',
+    'url': 'https://example.com/story',
+    'response_time_ms': 150,
+    'success': True,
+})
+
+mf.track(123456789, 'BUTTON_CLICK', {
+    'button_name': 'premium_upgrade',
+    'screen': 'main_menu',
+})
+
+mf.track(123456789, 'VIDEO_DOWNLOADED', {
+    'duration_seconds': 45,
+    'quality': '1080p',
+    'source': 'instagram',
+})
+
+mf.shutdown()
+```
+
+### Synchronous Client
+
+```python
+from metricsfirst import MetricsFirst, ServiceEventData
+
+# Initialize
+mf = MetricsFirst(
+    bot_id="your_bot_id",
+    api_key="your_api_key",
+)
+
+# Track a service (fire-and-forget, non-blocking)
+mf.track_service(ServiceEventData(
+    user_id=123456789,
+    service_name="image_generation",
+    is_free=False,
+    price=10,
+    currency="USD",
+))
+
+# Shutdown flushes remaining events
+mf.shutdown()
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from metricsfirst import AsyncMetricsFirst, ServiceEventData
+
+async def main():
+    # Initialize
+    mf = AsyncMetricsFirst(
+        bot_id="your_bot_id",
+        api_key="your_api_key",
+    )
+    await mf.start()
+
+    # Track events (fire-and-forget)
+    await mf.track_service(ServiceEventData(
+        user_id=123456789,
+        service_name="image_generation",
+    ))
+
+    # Shutdown
+    await mf.shutdown()
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+# Sync
+with MetricsFirst(bot_id="...", api_key="...") as mf:
+    mf.track_service(...)
+
+# Async
+async with AsyncMetricsFirst(bot_id="...", api_key="...") as mf:
+    await mf.track_service(...)
+```
+
+## Available Methods
+
+| Method                             | Description                                 |
+| ---------------------------------- | ------------------------------------------- |
+| `track()`                          | **Track custom events with any properties** |
+| `track_service()`                  | Track services provided                     |
+| `track_error()`                    | Track errors                                |
+| `track_error_from_exception()`     | Track error from exception                  |
+| `track_purchase_initiated()`       | Track purchase start                        |
+| `track_purchase_completed()`       | Track successful purchase                   |
+| `track_purchase_error()`           | Track failed purchase                       |
+| `track_recurring_charge_success()` | Track subscription charge                   |
+| `track_recurring_charge_failed()`  | Track failed charge                         |
+| `identify()`                       | Identify user with properties               |
+
+### track() - Custom Events
+
+```python
+mf.track(
+    user_id: int,                 # Telegram user ID
+    event_name: str,              # Event name (e.g., 'STORY_RESPONSE')
+    properties: dict = None,      # Any key-value pairs
+)
+```
+
+## Configuration
+
+```python
+mf = MetricsFirst(
+    bot_id="your_bot_id",
+    api_key="your_api_key",
+    api_url="https://api.metricsfirst.com",  # Custom API URL
+    batch_events=True,      # Batch events before sending
+    batch_size=10,          # Events per batch
+    batch_interval=5.0,     # Seconds between flushes
+    debug=False,            # Enable debug logging
+    timeout=10.0,           # HTTP timeout
+)
+```
+
+## License
+
+MIT

metricsfirst-0.1.7.dist-info/RECORD

@@ -0,0 +1,9 @@
+metricsfirst/__init__.py,sha256=VLKKlbrfHZC9VNRPlaWRl8TOX-EWHo_oQ6XizZcxBvA,585
+metricsfirst/async_client.py,sha256=1l7o3rJ04GqgjIzThiApgwUudFiLqjuTdyT_8SWDPmY,12610
+metricsfirst/client.py,sha256=y9Mns-azaNooYKcIcSd8EKx9IJWNzeiW-aP5edNehQg,12091
+metricsfirst/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metricsfirst/types.py,sha256=YrQE_lg8IoAFRCks5wSCM6js5bdL_zh8QCJBYE1G7s8,3392
+metricsfirst-0.1.7.dist-info/METADATA,sha256=iWXX-ctVf2quEY965apva3M7cnQAgVKDz_0RWdwrcNE,5996
+metricsfirst-0.1.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+metricsfirst-0.1.7.dist-info/licenses/LICENSE,sha256=Y-1JOUpozrNJlHFFq4HOB7Fc7L7lWmnIXAARWLo9ZnE,1070
+metricsfirst-0.1.7.dist-info/RECORD,,

metricsfirst-0.1.7.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

metricsfirst-0.1.7.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 MetricsFirst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+