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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user