John O'Keefe
7c7e282e79
Archaeology, prompted by the user asking when it broke: the builder's save NEVER worked. The page was born (2026-02-19,a92bf99a) posting auto_assign_rules as a JSON-encoded STRING into an endpoint that has bound []Rule since its creation (2026-01-31,6495cc2c), plus fields (manual_book_ids, match_type, library_id, show_on_dashboard) the endpoint never accepted. The preview button hit a real endpoint, so the page looked alive while Save always failed at request binding. Verified live before this change: the page's exact payload 400'd "invalid request" against the unmodified server. The fix adapts the builder's payload at write time — the legacy rules vocabulary converts to a filter tree (RulesToFilterTree restored from the retirement commit as the single write path, unit test restored with it): - match_type seeds the converted tree's root mode (any default). - manual_book_ids attach to the created collection after create (unparsable ids skipped — the AddBooks leniency). - show_on_dashboard persists (new create field). - Converted trees validate under ParseFilterTree: an unhonorable rule is a 400 at write naming the problem, never a stored 500 at render. Dashboard sections: smart user sections now evaluate their tree LIVE — GetUserCollectionItems merges stored membership with the composed engine's matches (deduped, library-scoped, capped at the section limit). This exposed a REAL production wiring bug: every production NewDashboardService call omitted the search service, so tree evaluation through the dashboard could never have worked (the test harness wired it correctly — the gap was production-only and latent, because nothing in the dashboard evaluated trees before this migration). The dashboard handler and both inline sites now receive the search service, and evaluation failures log instead of silently emptying a section. Supersedes the same-day loud-400 stance for the builder's payload (contract_pins migration entry); custom-section-builder.md documents the save contract; the create_collection API doc gains the adapted fields. New TestCustomSectionBuilderSave/BadRule pin the payload → tree → dashboard-render path end to end. Full container suite green (155s).
4.3 KiB
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:
{
"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:
{
"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:
Save contract (2026-10-31 tree migration): the rules array travels
as a JSON-encoded string and the server converts it to a filter tree at
write time — match_type seeds the tree's root mode (any default),
manual_book_ids attach to the created collection, and
show_on_dashboard persists. library_id is selection context only
(sections scope to the dashboard's active library at render). Invalid
rules are a 400 at write naming the problem; the section renders stored
picks + the tree's live matches, deduped.
{
"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
{
"rules": [
{
"field": "genre",
"operator": "equals",
"value": "Sci-Fi"
}
]
}
High Rated Books
{
"rules": [
{
"field": "rating",
"operator": "greater_than",
"value": "4"
}
]
}
Long Books (Manual Selection)
{
"manual_book_ids": ["uuid1", "uuid2", "uuid3"]
}
Recently Finished Audiobooks
{
"rules": [
{
"field": "format",
"operator": "equals",
"value": "Audiobook"
},
{
"field": "last_read",
"operator": "last_x_days",
"value": "30"
}
]
}