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