john-okeefe
da33e2c126
Updated Carousel Dashboard documentation to reflect finalized architecture decisions and resolve discrepancies between plan and verification checklist. ## CAROUSEL_DASHBOARD_PLAN.md Changes ### Added Phase 4.5: Collections Preview Endpoint - Documented why preview endpoint is required (web UI + mobile apps) - Explained why client-side preview is a bad idea (download entire library, code duplication, maintenance nightmare) - Added full PreviewCollection handler implementation - Added Bruno test specification ### Enhanced Phase 7: Router Registration & Config Setup - Renamed from "Router Registration" to "Router Registration & Config Setup" - Added Step 1: Update router.go Config struct with line numbers - Added Step 2: Update main.go initialization with line numbers - Added Step 3: Update test_helpers.go with line numbers - Added explanation: Why both DashboardService AND DashboardHandler? ### Updated Phase 10.5.4: Collections Preview Endpoint - Referenced Phase 4.5 (endpoint already implemented earlier) - Clarified needed for web UI AND mobile apps - Noted no additional work needed ### Added Phase 10.6: Implementation Checklist - 30+ checklist items with file paths and verification commands - Organized by layer (Database, Service, Handler, Router, Templates, TypeScript, Tests, Docs) - Added Build & Verification section - Added Timeline Estimate (20-26 hours) - Added Post-Implementation Tasks ## CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md Changes ### Added Clarification Section (at top) - Explained all discrepancies between plan and checklist - Preview endpoint IS in plan (Phase 4.5) - Custom Section Builder IS in plan (Phase 10.5.2 and 10.5.3) - Service method names - Plan is correct - Config struct - Documented with exact line numbers - DashboardService vs DashboardHandler - Explained why both needed ### Updated Service Method Names (Section 3.2) Changed to match plan's actual implementation: - GetDashboardSections (not GetSectionItems) - filterHiddenCollections (not filterHiddenSections) - reorderCollections (not reorderSections) - sortByPriority (new method) - getUserCollectionItems (not getCollectionSections) - getCollectionItemsByQueryType (renamed) ### Enhanced Config Verification (Section 6.4) Added exact line numbers for all 3 files: - internal/router/router.go lines 58-59 - cmd/server/main.go lines 123-124, 172-173 - cmd/server/tests/test_helpers.go lines 419-420, 458-459 ### Updated Preview Endpoint Section (Section 6.3) Added clear explanation of why endpoint is REQUIRED and why NOT client-side. ### Clarified Custom Section Builder (Sections 8.5, 9.4) Both now explicitly state "IS in the plan (Phase 10.5)" ## docs/developer/api/dashboard.md Changes Updated API documentation to match new unified collections architecture: - Terminology: "smart sections" → "system collections" - Field: `type: string` → `is_system: boolean` - Field: `id` → `media_item_id` for books - Request: `hidden_sections` → `hidden_collections` - Request: `section_order` → `collection_order` - Removed: "in-progress" and "unread" smart sections - Added: Update Dashboard Preferences endpoint - Added: Restore System Collection endpoint - Updated: Example responses with new field names and types - Updated: Error responses table ## Impact These changes clarify: 1. Preview endpoint is required for both web UI custom section builder and mobile apps 2. Custom Section Builder IS a major feature in the plan (not missing) 3. Service method names use "collections" terminology consistently 4. Config struct updates are clearly documented with exact line numbers (3 files only) 5. Why both DashboardService AND DashboardHandler are needed in Config All documentation now accurately reflects the finalized Carousel Dashboard architecture.
142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
# Dashboard API
|
|
|
|
## Get Dashboard Sections
|
|
|
|
Retrieve all dashboard sections for a specific library, including system collections and user collections.
|
|
|
|
**Endpoint**: `GET /api/dashboard/sections`
|
|
|
|
**Authentication**: Required (Bearer token)
|
|
|
|
### Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|--------|----------|-----------------------------------------------|
|
|
| library_id| string | Yes | Library UUID to fetch sections for |
|
|
| limit | number | No | Items per section (default: 20, max: 100) |
|
|
|
|
### Response
|
|
|
|
Returns array of sections in user's customized order (respects `collection_order` and `hidden_collections` preferences).
|
|
|
|
**Section Types**:
|
|
- `is_system: true`: System collections (4 pre-seeded defaults)
|
|
- `is_system: false`: User-created collections with `show_on_dashboard: true`
|
|
|
|
**System Collections**:
|
|
| ID | Title | Icon | Description |
|
|
|-----------------|------------------|------|--------------------------------------------------|
|
|
| continue-reading| Continue Reading | 📖 | Books with progress > 0% and < 100% |
|
|
| recently-added | Recently Added | 🆕 | Newest items in library |
|
|
| recently-read | Recently Read | ✅ | Books with progress = 100% |
|
|
| not-started | Not Started | 📕 | Books with no reading progress |
|
|
|
|
### Example Response
|
|
|
|
```json
|
|
{
|
|
"sections": [
|
|
{
|
|
"id": "continue-reading",
|
|
"is_system": true,
|
|
"title": "Continue Reading",
|
|
"description": "Books you're currently reading (0 < progress < 1)",
|
|
"icon": "📖",
|
|
"items": [
|
|
{
|
|
"media_item_id": "uuid-here",
|
|
"title": "Book Title",
|
|
"author": "Author Name",
|
|
"cover_image_path": "/path/to/cover.jpg"
|
|
}
|
|
],
|
|
"view_all_url": "/section/continue-reading",
|
|
"priority": 1
|
|
},
|
|
{
|
|
"id": "collection-uuid",
|
|
"is_system": false,
|
|
"title": "My Favorites",
|
|
"description": "My favorite books",
|
|
"icon": "⭐",
|
|
"items": [],
|
|
"view_all_url": "",
|
|
"priority": 100
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### User Preferences
|
|
|
|
The endpoint respects user's dashboard preferences:
|
|
|
|
- **`collection_order`**: Sections returned in user's custom order
|
|
- **`hidden_collections`**: Hidden collections excluded from response
|
|
- **`items_per_section`**: Default limit from user preferences (overridden by `?limit=` query param)
|
|
|
|
## Update Dashboard Preferences
|
|
|
|
Save or update user dashboard preferences for a specific library.
|
|
|
|
**Endpoint**: `PUT /api/dashboard/preferences`
|
|
|
|
**Authentication**: Required (Bearer token)
|
|
|
|
### Request Body
|
|
|
|
```json
|
|
{
|
|
"library_id": "uuid",
|
|
"hidden_collections": ["not-started"],
|
|
"collection_order": ["recently-added", "continue-reading", "recently-read"],
|
|
"items_per_section": 20
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
Returns updated preferences object.
|
|
|
|
## Restore System Collection
|
|
|
|
Reset a system collection to its default state (removes user customizations).
|
|
|
|
**Endpoint**: `POST /api/dashboard/restore-system-collection`
|
|
|
|
**Authentication**: Required (Bearer token)
|
|
|
|
### Request Body
|
|
|
|
```json
|
|
{
|
|
"collection_name": "continue-reading"
|
|
}
|
|
```
|
|
|
|
Valid `collection_name` values:
|
|
- `continue-reading`
|
|
- `recently-added`
|
|
- `recently-read`
|
|
- `not-started`
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"message": "System collection restored to defaults"
|
|
}
|
|
```
|
|
|
|
### Error Responses
|
|
|
|
| Status | Description |
|
|
|--------|--------------------------------|
|
|
| 400 | Missing library_id |
|
|
| 400 | Invalid library_id |
|
|
| 400 | Invalid collection_name |
|
|
| 401 | Unauthorized |
|
|
| 500 | Failed to load sections |
|
|
| 500 | Failed to save preferences |
|
|
| 500 | Failed to restore collection |
|