# Tracking API Documentation

The tracking service provides analytics about endpoint usage with time-based filtering.

## Authentication

In production, all tracking endpoints require Bearer token authentication:
```
Authorization: Bearer <your-api-token>
```

## Endpoints

### GET /api/tracking/stats

Get endpoint statistics with optional time period filtering.

**Query Parameters:**
- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)

**Examples:**
```bash
# Get all-time stats
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats

# Get last week's stats
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=week

# Get last 30 days
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=month
```

**Response:**
```json
{
  "stats": [
    {
      "endpoint": "/",
      "method": "GET",
      "hit_count": 245,
      "unique_users": 89,
      "last_access": "2025-08-13T10:30:00Z",
      "first_access": "2025-08-06T14:22:00Z"
    }
  ],
  "period": "week",
  "total_endpoints": 8
}
```

### GET /api/tracking/summary

Get overall tracking summary for a time period.

**Query Parameters:**
- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)

**Examples:**
```bash
# Get today's summary
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=day

# Get yearly summary
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=year
```

**Response:**
```json
{
  "period": "day",
  "total_hits": 1247,
  "total_endpoints": 12,
  "total_unique_users": 234,
  "oldest_visit": "2025-08-13T00:15:00Z",
  "newest_visit": "2025-08-13T23:45:00Z",
  "tracking_active": true
}
```

### GET /api/tracking/trends

Get visit trends over time with configurable granularity.

**Query Parameters:**
- `granularity` (optional): `hour`, `day`, `week`, `month` (default: `day`)
- `period` (optional): `24h`, `7d`, `30d`, `1y` (default: `7d`)

**Examples:**
```bash
# Hourly trends for last 24 hours
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=hour&period=24h

# Daily trends for last 30 days
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=day&period=30d

# Weekly trends for last year
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=week&period=1y
```

**Response:**
```json
{
  "trends": [
    {
      "time_bucket": "2025-08-13",
      "hits": 567,
      "unique_users": 123,
      "unique_endpoints": 8
    },
    {
      "time_bucket": "2025-08-12",
      "hits": 445,
      "unique_users": 98,
      "unique_endpoints": 7
    }
  ],
  "granularity": "day",
  "period": "7d"
}
```

### GET /api/tracking/visits

Get recent individual visits with optional filtering.

**Query Parameters:**
- `limit` (optional): Number of visits to return (default: `50`)

**Example:**
```bash
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/visits?limit=20
```

**Response:**
```json
{
  "visits": [
    {
      "user_hash": "a1b2c3d4e5f6...",
      "endpoint": "/boxes",
      "method": "GET",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "referer": "https://google.com",
      "timestamp": "2025-08-13T15:30:00Z"
    }
  ],
  "count": 20
}
```

## Benefits of This Approach

1. **No Duplication**: Single source of truth in `user_visits` table
2. **Flexible Querying**: Any time period can be queried on-demand
3. **Rich Analytics**: Detailed trends and user behavior insights
4. **Efficient Storage**: Only raw visits stored, stats calculated in real-time
5. **Historical Analysis**: Can analyze any historical period without pre-aggregation

## Performance Considerations

- Indexes are created on `timestamp`, `endpoint`, and `user_hash` for fast queries
- For very high traffic, consider adding materialized views for common time periods
- The SQLite database handles thousands of requests efficiently with proper indexing