Metadata-Version: 2.5
Name: junglans-trail
Version: 0.6.0
Summary: Embedded local-first analytics & on-page heatmap suite for Python (FastAPI, Starlette) by Junglans with 104 capabilities.
Project-URL: Homepage, https://junglans.in
Project-URL: Documentation, https://junglans.in
Project-URL: Repository, https://github.com/junglans/trail
Author-email: Junglans <contact@junglans.in>
License-Expression: MIT
Keywords: analytics,fastapi,heatmaps,junglans,local-first,privacy-first,self-hosted,starlette
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
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
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Requires-Dist: starlette>=0.27.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: urllib3>=1.26.0; extra == 'all'
Provides-Extra: client
Requires-Dist: urllib3>=1.26.0; extra == 'client'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Description-Content-Type: text/markdown

# junglans-trail

> **Embedded local-first analytics & on-page heatmap middleware for Python (FastAPI & Starlette).**  
> Developed by **Junglans** &bull; [junglans.in](https://junglans.in)

104 Capabilities. Zero standalone servers. Store all analytics and user telemetry directly in your application's local SQLite database under `/api/jungtrail`.

---

## Installation

### With `uv` (Recommended)
```bash
uv add junglans-trail
```

### With `pip`
```bash
pip install junglans-trail
```

---

## 30-Second Quickstart (FastAPI)

Mount the analytics router onto your existing FastAPI app in 3 lines:

```python
from fastapi import FastAPI
from junglans_trail import jungtrail_fastapi_middleware

app = FastAPI()

# Mounts all 104 analytics, heatmap, auth, and e-commerce endpoints under /api/jungtrail
storage = jungtrail_fastapi_middleware(
    app,
    db_name="analytics.db",       # Custom SQLite WAL database name
    db_path="data/analytics.db",  # Custom database storage path
    admin_key="your-admin-secret" # Protects stats, export, and heatmap endpoints
)

@app.get("/")
def home():
    return {"message": "Hello from Junglans Trail"}
```

---

## Backend Event Tracking in Python

Track backend business, auth, and e-commerce events directly from Python:

```python
from junglans_trail import TrailClient

client = TrailClient(
    endpoint="http://localhost:8000/api/jungtrail",
    write_key="optional-key"
)

# E-Commerce transaction
client.track(
    event_type="purchase",
    route="/checkout/success",
    meta={"order_id": "ord_9901", "revenue": 149.00, "items_count": 2}
)

# Auth & session telemetry
client.track(
    event_type="login_success",
    route="/api/v1/auth/login",
    meta={"provider": "github", "user_id": "usr_abc"}
)

client.flush()
```

---

## REST Endpoints Overview

| Route | Method | Description |
|---|---|---|
| `/api/jungtrail/events` | `POST` | Ingest batch telemetry events |
| `/api/jungtrail/heatmap` | `GET` | Coordinates for live visual DOM heatmap |
| `/api/jungtrail/stats` | `GET` | Core analytics: clicks, views, scroll, errors, vitals |
| `/api/jungtrail/stats/ecommerce` | `GET` | Revenue, orders, AOV, cart additions & drop-offs |
| `/api/jungtrail/stats/experiments` | `GET` | A/B testing variants, conversions, feature flags |
| `/api/jungtrail/stats/feedback` | `GET` | NPS score (Promoter/Passive/Detractor), CSAT, notes |
| `/api/jungtrail/stats/auth` | `GET` | Login rates, registration funnel, password resets, MFA |
| `/api/jungtrail/stats/session` | `GET` | Active sessions, duration, bounce rate, multi-tab sync |
| `/api/jungtrail/session/stitch` | `POST` | Retroactively stitch anonymous session to user ID |
| `/api/jungtrail/session/purge` | `POST`/`DELETE` | GDPR right-to-erasure user/session purge |
| `/api/jungtrail/export` | `GET` | Export database in JSON or CSV format |
| `/api/jungtrail/backup` | `GET` | Full SQLite database snapshot backup |
| `/api/jungtrail/health` | `GET` | Public status and version check |

---

## Developer & Organization

* **Organization**: [Junglans](https://junglans.in)
* **Website**: [https://junglans.in](https://junglans.in)
* **Email**: contact@junglans.in
* **License**: MIT
