diff --git a/docs/developer/api/saved-filters/index.md b/docs/developer/api/saved-filters/index.md new file mode 100644 index 0000000..cf572fb --- /dev/null +++ b/docs/developer/api/saved-filters/index.md @@ -0,0 +1,106 @@ +# Saved Filters API + +## Overview + +The Saved Filters API allows users to save and load custom filter presets for any resource type (media-items, collections, devices, etc.). Filters are user-specific and automatically scoped via JWT authentication. + +**Base URL:** `/api/saved-filters` + +**Authentication:** JWT token required (Bearer token) + +--- + +## Endpoints + +### GET /api/saved-filters + +Retrieve all saved filters for the authenticated user and a specific resource type. + +**Query Parameters:** +- `resource_type` (string, required) - Filter by resource type (e.g., "media-items", "collections") + +**Response:** Array of saved filter objects + +**Example Request:** +```bash +curl -H "Authorization: Bearer YOUR_TOKEN" \\ + "http://localhost:8765/api/saved-filters?resource_type=media-items" +``` + +**Example Response:** +```json +[ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "My Sci-Fi Books", + "resource_type": "media-items", + "filters": { + "genre_filter": "Science Fiction", + "sort": "title ASC" + }, + "created_at": "2024-03-20T12:00:00Z", + "updated_at": "2024-03-20T12:00:00Z" + } +] +``` + +--- + +### POST /api/saved-filters + +Create a new saved filter for the authenticated user. + +**Request Body:** +```json +{ + "name": "My Custom Filter", + "resource_type": "media-items", + "filters": { + "search": "keyword", + "author_filter": "Author Name", + "genre_filter": "Genre", + "sort": "title ASC" + } +} +``` + +**Validation:** +- `name` (string, required, max 100 chars) - Must be unique per user + resource type +- `resource_type` (string, required) - Must be valid resource type +- `filters` (object, required) - Key-value pairs of filter criteria + +**Response:** Created filter object (HTTP 201) + +**Error Responses:** +- 409 Conflict - Filter name already exists for this user + resource type + +--- + +### PUT /api/saved-filters/:id + +Update an existing saved filter. + +**URL Parameters:** +- `id` (UUID, required) - Filter ID to update + +**Request Body:** Same as POST + +**Response:** Updated filter object + +**Error Responses:** +- 404 Not Found - Filter doesn't exist or doesn't belong to user +- 409 Conflict - New name conflicts with existing filter + +--- + +### DELETE /api/saved-filters/:id + +Delete a saved filter. + +**URL Parameters:** +- `id` (UUID, required) - Filter ID to delete + +**Response:** 204 No Content (success) + +**Error Responses:** +- 404 Not Found - Filter doesn't exist or doesn't belong to user diff --git a/docs/user/library-browsing.md b/docs/user/library-browsing.md new file mode 100644 index 0000000..23fb1be --- /dev/null +++ b/docs/user/library-browsing.md @@ -0,0 +1,19 @@ +## Saving Custom Filters + +The bookshelf page allows you to save custom filter presets for quick access. + +### How to Save a Filter + +1. Navigate to the **All Books** page +2. Set your desired filters (genre, author, series, etc.) +3. Click the **💾 Save Filter** button +4. Enter a name for your filter (e.g., "My Sci-Fi Books") +5. Click **Save** + +### Loading Saved Filters + +After saving filters, you can quickly load them from the saved filters dropdown (feature coming soon). For now, saved filters persist across page refreshes. + +### Filter Privacy + +Saved filters are **private to your account**. Other users cannot see or modify your filters.