# 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

## Quick Start

### 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 Events

| Method                             | Description                   |
| ---------------------------------- | ----------------------------- |
| `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 |

## 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
