# 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   |