feat(api,web): tier-based session limits and daily turn usage display

Backend Changes:
- Add tier-based max_sessions config (free: 1, basic: 2, premium: 3, elite: 5)
- Add DELETE /api/v1/sessions/{id} endpoint for hard session deletion
- Cascade delete chat messages when session is deleted
- Add GET /api/v1/usage endpoint for daily turn limit info
- Replace hardcoded TIER_LIMITS with config-based ai_calls_per_day
- Handle unlimited (-1) tier in rate limiter service

Frontend Changes:
- Add inline session delete buttons with HTMX on character list
- Add usage_display.html component showing remaining daily turns
- Display usage indicator on character list and game play pages
- Page refresh after session deletion to update UI state

Documentation:
- Update API_REFERENCE.md with new endpoints and tier limits
- Update API_TESTING.md with session endpoint examples
- Update SESSION_MANAGEMENT.md with tier-based limits

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-11-26 10:00:45 -06:00
parent 0a7156504f
commit 61a42d3a77
15 changed files with 768 additions and 59 deletions

View File

@@ -1447,6 +1447,166 @@ curl http://localhost:5000/api/v1/origins
---
## Session Endpoints
### 1. Create Session
**Endpoint:** `POST /api/v1/sessions`
**Description:** Create a new game session for a character. Subject to tier-based limits (Free: 1, Basic: 2, Premium: 3, Elite: 5).
**Request:**
```bash
# httpie
http --session=user1 POST localhost:5000/api/v1/sessions \
character_id="char_123"
# curl
curl -X POST http://localhost:5000/api/v1/sessions \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{
"character_id": "char_123"
}'
```
**Success Response (201 Created):**
```json
{
"app": "Code of Conquest",
"version": "0.1.0",
"status": 201,
"timestamp": "2025-11-26T10:30:00Z",
"result": {
"session_id": "sess_789",
"character_id": "char_123",
"turn_number": 0,
"game_state": {
"current_location": "crossville_village",
"location_type": "town",
"active_quests": []
}
}
}
```
**Error Response (409 Conflict - Session Limit Exceeded):**
```json
{
"app": "Code of Conquest",
"version": "0.1.0",
"status": 409,
"timestamp": "2025-11-26T10:30:00Z",
"error": {
"code": "SESSION_LIMIT_EXCEEDED",
"message": "Maximum active sessions reached for free tier (1/1). Please delete an existing session to start a new one."
}
}
```
---
### 2. List Sessions
**Endpoint:** `GET /api/v1/sessions`
**Description:** Get all active sessions for the authenticated user.
**Request:**
```bash
# httpie
http --session=user1 GET localhost:5000/api/v1/sessions
# curl
curl http://localhost:5000/api/v1/sessions -b cookies.txt
```
**Success Response (200 OK):**
```json
{
"app": "Code of Conquest",
"version": "0.1.0",
"status": 200,
"timestamp": "2025-11-26T10:30:00Z",
"result": [
{
"session_id": "sess_789",
"character_id": "char_123",
"turn_number": 5,
"status": "active",
"created_at": "2025-11-26T10:00:00Z",
"last_activity": "2025-11-26T10:25:00Z",
"game_state": {
"current_location": "crossville_village",
"location_type": "town"
}
}
]
}
```
---
### 3. Delete Session
**Endpoint:** `DELETE /api/v1/sessions/<session_id>`
**Description:** Permanently delete a session and all associated chat messages. This frees up a session slot for your tier limit.
**Request:**
```bash
# httpie
http --session=user1 DELETE localhost:5000/api/v1/sessions/sess_789
# curl
curl -X DELETE http://localhost:5000/api/v1/sessions/sess_789 \
-b cookies.txt
```
**Success Response (200 OK):**
```json
{
"app": "Code of Conquest",
"version": "0.1.0",
"status": 200,
"timestamp": "2025-11-26T10:30:00Z",
"result": {
"message": "Session deleted successfully",
"session_id": "sess_789"
}
}
```
**Error Response (404 Not Found):**
```json
{
"app": "Code of Conquest",
"version": "0.1.0",
"status": 404,
"timestamp": "2025-11-26T10:30:00Z",
"error": {
"code": "NOT_FOUND",
"message": "Session not found"
}
}
```
**Note:** Deleting a session:
- Permanently removes the session from the database
- Deletes all chat messages associated with the session
- Cannot be undone
- Frees up a session slot for your tier limit
---
## Testing Workflows
### Complete Registration Flow