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>
2025-11-26 10:00:45 -06:00
parent 0a7156504f
commit 61a42d3a77
15 changed files with 768 additions and 59 deletions
--- a/api/docs/API_REFERENCE.md
+++ b/api/docs/API_REFERENCE.md
@@ -875,7 +875,30 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 **Error Responses:**
 - `400` - Validation error (missing character_id)
 - `404` - Character not found
- `409` - Session limit exceeded (max 5 active sessions)
+- `409` - Session limit exceeded (tier-based limit)
+
+**Session Limits by Tier:**
+| Tier | Max Active Sessions |
+|------|---------------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |
+
+**Error Response (409 Conflict - Session Limit Exceeded):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 409,
+  "timestamp": "2025-11-16T10:30:00Z",
+  "result": null,
+  "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."
+  }
+}
+```

 ---

@@ -1096,24 +1119,39 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age

 ---

-### End Session
+### Delete Session

 | | |
 |---|---|
 | **Endpoint** | `DELETE /api/v1/sessions/<session_id>` |
-| **Description** | End and archive session |
+| **Description** | Permanently delete a session and all associated chat messages |
 | **Auth Required** | Yes |

+**Behavior:**
+- Permanently removes the session from the database (hard delete)
+- Also deletes all chat messages associated with this session
+- Frees up the session slot for the user's tier limit
+- Cannot be undone
+
 **Response (200 OK):**
 ```json
 {
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-16T10:30:00Z",
  "result": {
-    "message": "Session ended",
-    "final_state": {}
+    "message": "Session deleted successfully",
+    "session_id": "sess_789"
  }
 }
 ```

+**Error Responses:**
+- `401` - Not authenticated
+- `404` - Session not found or not owned by user
+- `500` - Internal server error
+
 ---

 ### Export Session
@@ -2589,6 +2627,7 @@ GET /api/v1/characters/char_123/chats/search?q=quest&npc_id=npc_grom_ironbeard&c
 | `INVALID_INPUT` | 400 | Validation error |
 | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
 | `CHARACTER_LIMIT_EXCEEDED` | 400 | User has reached character limit for their tier |
+| `SESSION_LIMIT_EXCEEDED` | 409 | User has reached session limit for their tier |
 | `CHARACTER_NOT_FOUND` | 404 | Character does not exist or not accessible |
 | `SKILL_UNLOCK_ERROR` | 400 | Skill unlock failed (prerequisites, points, or tier) |
 | `INSUFFICIENT_FUNDS` | 400 | Not enough gold |
@@ -2602,12 +2641,12 @@ GET /api/v1/characters/char_123/chats/search?q=quest&npc_id=npc_grom_ironbeard&c

 ## Rate Limiting

-| Tier | Requests/Minute | AI Calls/Day |
-|------|-----------------|--------------|
-| FREE | 30 | 50 |
-| BASIC | 60 | 200 |
-| PREMIUM | 120 | 1000 |
-| ELITE | 300 | Unlimited |
+| Tier | Requests/Minute | AI Calls/Day | Max Sessions |
+|------|-----------------|--------------|--------------|
+| FREE | 30 | 50 | 1 |
+| BASIC | 60 | 200 | 2 |
+| PREMIUM | 120 | 1000 | 3 |
+| ELITE | 300 | Unlimited | 5 |

 **Rate Limit Headers:**
 ```
--- a/api/docs/API_TESTING.md
+++ b/api/docs/API_TESTING.md
@@ -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
--- a/api/docs/SESSION_MANAGEMENT.md
+++ b/api/docs/SESSION_MANAGEMENT.md
@@ -126,13 +126,21 @@ session = service.create_solo_session(

 **Validations:**
 - User must own the character
- User cannot exceed 5 active sessions
+- User cannot exceed their tier's session limit
+
+**Session Limits by Tier:**
+| Tier | Max Sessions |
+|------|--------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |

 **Returns:** `GameSession` instance

 **Raises:**
 - `CharacterNotFound` - Character doesn't exist or user doesn't own it
- `SessionLimitExceeded` - User has 5+ active sessions
+- `SessionLimitExceeded` - User has reached their tier's session limit

 ### Retrieving Sessions

@@ -284,10 +292,18 @@ session = service.add_world_event(

 | Limit | Value | Notes |
 |-------|-------|-------|
-| Active sessions per user | 5 | End existing sessions to create new |
+| Active sessions per user | Tier-based (1-5) | See tier limits below |
 | Active quests per session | 2 | Complete or abandon to accept new |
 | Conversation history | Unlimited | Consider archiving for very long sessions |

+**Session Limits by Tier:**
+| Tier | Max Sessions |
+|------|--------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |
+
 ---

 ## Database Schema
@@ -400,7 +416,7 @@ except SessionNotFound:
 try:
    service.create_solo_session(user_id, char_id)
 except SessionLimitExceeded:
-    # User has 5+ active sessions
+    # User has reached their tier's session limit
    pass

 try: