# Custom Section Builder API

The Custom Section Builder allows users to create personalized dashboard sections by defining filter rules or manually selecting books.

## Preview Collection

Evaluates filter rules and returns matching items without saving the collection.

**Endpoint:** `POST /api/collections/preview`

**Request Body:**

```json
{
  "library_id": "uuid",
  "rules": [
    {
      "id": "rule1",
      "field": "genre",
      "operator": "equals",
      "value": "Sci-Fi",
      "priority": 1
    }
  ],
  "manual_book_ids": ["uuid1", "uuid2"],
  "limit": 20
}
```

**Available Filter Fields:**

| Field        | Type   | Operators                                                                |
| ------------ | ------ | ------------------------------------------------------------------------ |
| `title`      | text   | contains, equals, starts_with, ends_with, regex                          |
| `author`     | text   | contains, equals                                                         |
| `genre`      | select | equals, not_equals, in, not_in                                           |
| `series`     | text   | is_set, is_not_set, equals, contains                                     |
| `progress`   | number | equals, not_equals, greater_than, less_than, between, is_set, is_not_set |
| `rating`     | number | equals, not_equals, greater_than, less_than, is_set, is_not_set          |
| `date_added` | date   | equals, not_equals, before, after, between, last_x_days                  |
| `last_read`  | date   | equals, before, after, between, last_x_days, is_set, is_not_set          |
| `publisher`  | text   | contains, equals                                                         |
| `language`   | select | equals, not_equals, in                                                   |
| `format`     | select | equals, in                                                               |
| `tags`       | text   | contains, not_contains, equals                                           |
| `narrators`  | text   | contains, equals, is_set, is_not_set                                     |

**Response:**

```json
{
  "items": [
    {
      "media_item_id": "uuid",
      "title": "Book Title",
      "author": "Author Name",
      "cover_image_path": "/path/to/cover.jpg"
    }
  ]
}
```

## Create Custom Section

Creates a new custom collection with filter rules and/or manual book selection.

**Endpoint:** `POST /api/collections`

**Request Body:**

```json
{
  "name": "My Custom Section",
  "description": "My favorite Sci-Fi books",
  "icon": "📚",
  "color": "#9333ea",
  "show_on_dashboard": true,
  "auto_assign_rules": "[{\"id\":\"rule1\",\"field\":\"genre\",\"operator\":\"equals\",\"value\":\"Sci-Fi\",\"priority\":1}]",
  "manual_book_ids": ["uuid1", "uuid2"],
  "view_settings": {}
}
```

**Response:** Returns the created collection object.

## Frontend Implementation

**Route:** `/custom-section`

**Template:** `templates/custom_section.templ`

**TypeScript:** `web/src/custom-section-builder.ts`

Key features:

- 14 filter fields with various operators
- Live preview functionality
- Search + multi-select for manual book addition
- AND/OR logic support for combining rules

## Example Use Cases

### Sci-Fi Favorites

```json
{
  "rules": [
    {
      "field": "genre",
      "operator": "equals",
      "value": "Sci-Fi"
    }
  ]
}
```

### High Rated Books

```json
{
  "rules": [
    {
      "field": "rating",
      "operator": "greater_than",
      "value": "4"
    }
  ]
}
```

### Long Books (Manual Selection)

```json
{
  "manual_book_ids": ["uuid1", "uuid2", "uuid3"]
}
```

### Recently Finished Audiobooks

```json
{
  "rules": [
    {
      "field": "format",
      "operator": "equals",
      "value": "Audiobook"
    },
    {
      "field": "last_read",
      "operator": "last_x_days",
      "value": "30"
    }
  ]
}
```