bookhoard/bruno/media-items/search/Search All Libraries.yml

info:
  name: Search All Libraries
  type: http
  seq: 13

http:
  method: GET
  url: "{{base_url}}/api/media-items/search?q=foundation&library_id={{library_id}}"
  params:
    - name: q
      value: foundation
      type: query
    - name: library_id
      value: "{{library_id}}"
      type: query
    - name: author_filter
      value: ""
      type: query
      disabled: true
    - name: series_filter
      value: ""
      type: query
      disabled: true
    - name: tags_filter
      value: ""
      type: query
      disabled: true
    - name: language_filter
      value: ""
      type: query
      disabled: true
    - name: year_min
      value: ""
      type: query
      disabled: true
    - name: year_max
      value: ""
      type: query
      disabled: true
    - name: has_cover
      value: ""
      type: query
      disabled: true
    - name: sort
      value: title ASC
      type: query
      disabled: true
    - name: limit
      value: "50"
      type: query
      disabled: true
    - name: offset
      value: "0"
      type: query
      disabled: true
  auth: inherit

settings:
  encodeUrl: true
  timeout: 0
  followRedirects: true
  maxRedirects: 5

docs: |-
  ## Search All Libraries

  Searches for media items using the unified search endpoint. Supports fuzzy search, exact match, and filtering.

  **Method:** GET

  **Endpoint:** /api/media-items/search

  **Authentication:** Required (Bearer token)

  ## Query Parameters

  ### Search Parameters:
  - `q` (string, optional): Global search query
    - Fuzzy matching by default (tolerates typos)
    - Exact match with quotes: `"\"exact phrase\""`
    - Searches: title, author, series, tags, contributors
    - Example: `q=foundation` (fuzzy), `q="\"Foundation and Empire\""` (exact)

  ### Filter Parameters (All Fuzzy Except Years/Booleans):
  - `author_filter` (string, optional): Fuzzy match author field
    - Example: `author_filter=asimov` matches "Asimov, Isaac"

  - `series_filter` (string, optional): Fuzzy match series field
    - Example: `series_filter=harry` matches "Harry Potter"

  - `tags_filter` (string, optional): Fuzzy match tags field
    - Example: `tags_filter=scifi` matches "Sci-Fi", "Science Fiction"

  - `language_filter` (string, optional): Fuzzy match language field
    - Example: `language_filter=eng` matches "English", "eng"

  - `year_min` (integer, optional): Minimum copyright year (exact range)
    - Example: `year_min=2000`

  - `year_max` (integer, optional): Maximum copyright year (exact range)
    - Example: `year_max=2020`

  - `has_cover` (boolean, optional): Filter by cover image presence
    - Values: `true`, `false`, or empty (all)
    - Example: `has_cover=true`

  ### Pagination Parameters:
  - `limit` (integer, optional): Number of results (default: 50, max: 200)
    - Example: `limit=100`

  - `offset` (integer, optional): Number of results to skip (for pagination)
    - Example: `offset=50`

  - `sort` (string, optional): Sort order (default: relevance DESC, title ASC)
    - Options:
      - `title ASC` - Title A-Z
      - `title DESC` - Title Z-A
      - `author ASC` - Author A-Z
      - `author DESC` - Author Z-A
      - `created_at ASC` - Date added oldest first
      - `created_at DESC` - Date added newest first
      - `page_count ASC` - Page count low to high
      - `page_count DESC` - Page count high to low
    - Example: `sort=author ASC`

  ## How Fuzzy Matching Works

  **Text Filters (author, series, tags, language):**
  - Uses PostgreSQL pg_trgm word_similarity()
  - Threshold: 0.3 (30% similarity)
  - Handles typos: "azimov" → "Asimov"
  - Handles partial matches: "scifi" → "Sci-Fi"
  - Case-insensitive

  **Search Query (q parameter):**
  - **Fuzzy (default):** Matches similar words across title, author, series, tags
    - `q=foundation` → "Foundation", "Foundations", "The Foundation"
  - **Exact (with quotes):** Must match the exact phrase
    - `q="\"Foundation and Empire\""` → Only "Foundation and Empire"

  ## Response

  **HTTP 200 (OK):**
  ```json
  [
    {
      "id": "uuid",
      "title": "Foundation",
      "author": "Asimov, Isaac",
      "series": "Foundation",
      "tags": "Sci-Fi",
      "language": "English",
      "copyright_year": 1951,
      "page_count": 255,
      "cover_image_path": "/path/to/cover.jpg",
      "library_id": "uuid",
      "library_name": "E-Books",
      "library_type_name": "ebooks"
    }
  ]
  ```

  **HTTP 404 (Not Found):**
  ```json
  {
    "error": "no results found",
    "query": "foundation",
    "results": []
  }
  ```

  ## Examples

  **1. Simple search:**
  ```
  GET /api/media-items/search?q=harry&library_id={uuid}
  ```
  Returns books matching "harry" in title/author/series

  **2. Fuzzy author filter:**
  ```
  GET /api/media-items/search?author_filter=asimov&library_id={uuid}
  ```
  Returns books by authors similar to "asimov"

  **3. Combined search + filters:**
  ```
  GET /api/media-items/search?q=foundation&author_filter=asimov&tags_filter=scifi&library_id={uuid}
  ```
  Returns "foundation" books by "asimov" in "scifi" tags

  **4. Exact match with quotes:**
  ```
  GET /api/media-items/search?q="\"Foundation and Empire\""&library_id={uuid}
  ```
  Returns only exact title match

  **5. Year range + sorting:**
  ```
  GET /api/media-items/search?year_min=2000&year_max=2020&sort=created_at DESC&library_id={uuid}
  ```
  Returns books from 2000-2020 sorted by newest first

  **6. Boolean filter:**
  ```
  GET /api/media-items/search?has_cover=true&library_id={uuid}
  ```
  Returns only books that have cover images

  ## Success Criteria

  - Status: 200
  - Returns array of media items matching all filters
  - Results sorted by:
    1. Relevance score (when searching with `q`)
    2. User-specified sort parameter
    3. Title (final fallback)
  - Pagination works correctly with limit/offset