# OpenRouter API Key Monitor

Applicazione web multi-utente per monitorare l'utilizzo delle API key della piattaforma [OpenRouter](https://openrouter.ai/).

## 🚀 Caratteristiche

- **🔐 Autenticazione Sicura**: Registrazione e login con JWT
- **🔑 Gestione API Key**: CRUD completo con cifratura AES-256
- **📊 Dashboard Statistiche**: Visualizzazione utilizzo, costi, modelli
- **🔓 API Pubblica**: Accesso programmatico con token API
- **📈 Monitoraggio**: Tracciamento richieste, token, costi

## 📋 Requisiti

- Python 3.11+
- SQLite (incluso)
- Docker (opzionale)

## 🛠️ Installazione

### Installazione Locale

```bash
# Clona il repository
git clone https://github.com/username/openrouter-watcher.git
cd openrouter-watcher

# Crea virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# oppure: .venv\Scripts\activate  # Windows

# Installa dipendenze
pip install -r requirements.txt

# Configura variabili d'ambiente
cp .env.example .env
# Modifica .env con le tue configurazioni

# Esegui migrazioni database
alembic upgrade head

# Avvia applicazione
uvicorn src.openrouter_monitor.main:app --reload
```

### Installazione con Docker

```bash
# Avvia con Docker Compose
docker-compose up -d

# L'applicazione sarà disponibile su http://localhost:8000
```

## 🔧 Configurazione

Crea un file `.env` con le seguenti variabili:

```env
# Database
DATABASE_URL=sqlite:///./data/app.db

# Sicurezza (genera con: openssl rand -hex 32)
SECRET_KEY=your-super-secret-jwt-key-min-32-chars
ENCRYPTION_KEY=your-32-byte-encryption-key-here

# OpenRouter
OPENROUTER_API_URL=https://openrouter.ai/api/v1

# Limiti
MAX_API_KEYS_PER_USER=10
MAX_API_TOKENS_PER_USER=5
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=3600

# JWT
JWT_EXPIRATION_HOURS=24
```

## 📚 API Endpoints

### Autenticazione (JWT)

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| POST | `/api/auth/register` | Registrazione utente |
| POST | `/api/auth/login` | Login utente |
| POST | `/api/auth/logout` | Logout utente |

### Gestione API Keys OpenRouter

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| POST | `/api/keys` | Aggiungi API key |
| GET | `/api/keys` | Lista API keys |
| PUT | `/api/keys/{id}` | Aggiorna API key |
| DELETE | `/api/keys/{id}` | Elimina API key |

### Statistiche

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| GET | `/api/stats/dashboard` | Dashboard statistiche |
| GET | `/api/usage` | Dettaglio utilizzo |

### Gestione Token API

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| POST | `/api/tokens` | Genera token API |
| GET | `/api/tokens` | Lista token |
| DELETE | `/api/tokens/{id}` | Revoca token |

### API Pubblica (Autenticazione con Token API)

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| GET | `/api/v1/stats` | Statistiche aggregate |
| GET | `/api/v1/usage` | Dettaglio utilizzo |
| GET | `/api/v1/keys` | Lista API keys con stats |

## 🧪 Test

```bash
# Esegui tutti i test
pytest tests/unit/ -v

# Con coverage
pytest tests/unit/ -v --cov=src/openrouter_monitor

# Test specifici
pytest tests/unit/routers/test_auth.py -v
pytest tests/unit/routers/test_api_keys.py -v
pytest tests/unit/routers/test_public_api.py -v
```

## 📁 Struttura Progetto

```
openrouter-watcher/
├── src/openrouter_monitor/    # Codice sorgente
│   ├── schemas/              # Pydantic schemas
│   ├── models/               # SQLAlchemy models
│   ├── routers/              # FastAPI routers
│   ├── services/             # Business logic
│   ├── dependencies/         # FastAPI dependencies
│   └── main.py               # Entry point
├── tests/                     # Test suite
├── docs/                      # Documentazione
├── export/                    # Specifiche e progresso
└── prompt/                    # Prompt per AI agents
```

## 🔒 Sicurezza

- **Cifratura**: API keys cifrate con AES-256-GCM
- **Password**: Hash con bcrypt (12 rounds)
- **Token JWT**: Firma HMAC-SHA256
- **Token API**: Hash SHA-256 nel database
- **Rate Limiting**: 100 richieste/ora per token

## 📄 Licenza

MIT License

## 🤝 Contributing

Contributi sono benvenuti! Segui le linee guida in `.opencode/WORKFLOW.md`.

## 📞 Supporto

Per domande o problemi, apri un issue su GitHub.