silo-server/internal/catalog/browse.go

package catalog

import (
	"context"
	"fmt"
	"slices"
	"strconv"
	"strings"
	"time"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/Silo-Server/silo-server/internal/models"
)

// BrowseFilters represents all supported filter, sort, and pagination parameters
// for the /items browse endpoint.
type BrowseFilters struct {
	Type               string   // single type ("movie") or comma-separated ("movie,series")
	Genre              string   // single genre filter (GIN index)
	NamePrefix         string   // case-insensitive prefix filter on sort_title/title
	ContentIDs         []string // optional allowlist of exact content IDs
	LibraryID          int      // filter by specific library
	LibraryIDs         []int    // accessible library IDs (nil = all)
	DisabledLibraryIDs []int    // user-disabled libraries to exclude (only used when LibraryIDs is nil)
	MaxContentRating   string   // maximum allowed content rating ceiling
	YearMin            int      // minimum year (inclusive)
	YearMax            int      // maximum year (inclusive)
	ContentRating      []string // comma-separated content ratings (e.g., PG-13, TV-MA)
	Status             string   // pending, matched, unmatched (optional filter)
	PersonID           int64    // filter items by person (joins item_people)
	Sort               string   // created_at, release_date, rating_imdb, rating_tmdb, year, sort_title, recently_added
	Order              string   // asc, desc
	Limit              int
	Offset             int
	SnapshotAt         *time.Time // pagination fence: exclude items created after this timestamp
}

// BrowseResult contains the paginated result of a browse query.
type BrowseResult struct {
	Items   []*models.MediaItem `json:"items"`
	Total   int                 `json:"total"`
	HasMore bool                `json:"has_more"`
}

// BrowseRepository provides browse/filter queries on the media_items table.
type BrowseRepository struct {
	pool *pgxpool.Pool
}

// NewBrowseRepository creates a new BrowseRepository.
func NewBrowseRepository(pool *pgxpool.Pool) *BrowseRepository {
	return &BrowseRepository{pool: pool}
}

// Pool returns the underlying pgx pool for ad-hoc queries.
func (r *BrowseRepository) Pool() *pgxpool.Pool {
	return r.pool
}

// Browse executes a filtered, sorted, paginated query against media_items.
func (r *BrowseRepository) Browse(ctx context.Context, filters BrowseFilters) (*BrowseResult, error) {
	return r.browse(ctx, filters, true)
}

func (r *BrowseRepository) BrowsePage(ctx context.Context, filters BrowseFilters, includeTotal bool) (*BrowseResult, error) {
	return r.browse(ctx, filters, includeTotal)
}

func (r *BrowseRepository) browse(ctx context.Context, filters BrowseFilters, includeTotal bool) (*BrowseResult, error) {
	plan, earlyEmpty, err := r.buildBrowsePlan(filters)
	if err != nil {
		return nil, err
	}
	if earlyEmpty {
		return &BrowseResult{Items: []*models.MediaItem{}, Total: 0, HasMore: false}, nil
	}

	dataQuery, queryArgs := plan.pagedSQL(includeTotal)
	rows, err := r.pool.Query(ctx, dataQuery, queryArgs...)
	if err != nil {
		return nil, fmt.Errorf("browsing media items: %w", err)
	}
	defer rows.Close()

	var (
		items []*models.MediaItem
		total int
	)
	if includeTotal {
		items, total, err = scanBrowseItemsWithTotal(rows)
	} else {
		items, err = scanBrowseItems(rows)
	}
	if err != nil {
		return nil, err
	}

	hasMore := false
	if includeTotal {
		// COUNT(*) OVER () emits no rows when the data SELECT is empty, so
		// total stays 0 even when the broader result set has matching rows
		// (e.g. OFFSET past the last page). Re-query the count to give
		// callers the real total. Skip when offset == 0 because in that
		// case an empty page genuinely means total = 0.
		if len(items) == 0 && plan.offset > 0 {
			countSQL, countArgs := plan.countSQL()
			if err := r.pool.QueryRow(ctx, countSQL, countArgs...).Scan(&total); err != nil {
				return nil, fmt.Errorf("count fallback for empty browse page: %w", err)
			}
		}
		hasMore = total > plan.offset+plan.limit
	} else if len(items) > plan.limit {
		hasMore = true
		items = items[:plan.limit]
	}

	return &BrowseResult{
		Items:   items,
		Total:   total,
		HasMore: hasMore,
	}, nil
}

// browseQueryPlan captures the rendered SQL fragments and bound args for a
// browse data query. It is produced by buildBrowsePlan and consumed both by
// browse() (to execute) and by tests (to inspect the emitted SQL without a
// database).
type browseQueryPlan struct {
	selectClause  string
	fromClause    string
	whereClause   string
	groupByClause string
	orderBy       string
	// args holds bound values for the FROM/WHERE/GROUP BY portion of the
	// plan. orderArgs is kept separate so countSQL — which omits ORDER BY —
	// can bind only the args its SQL actually references. Combining the two
	// would make countSQL pass extra bound values past the count query's
	// placeholder set, and pgx/Postgres reject that with "bind message
	// supplies N parameters, but prepared statement requires M". The
	// random+SnapshotAt sort path (buildOrderByPlan) is the canonical case:
	// it bakes a bound timestamp arg into the ORDER BY expression that the
	// count query has no use for.
	args        []any
	orderArgs   []any
	limit       int
	offset      int
	limitArgIdx int // 1-based bound-arg index for the LIMIT param
}

// countSQL renders a count-only query that returns the total number of rows
// matching the plan's FROM/WHERE/GROUP BY, ignoring LIMIT/OFFSET/ORDER BY.
// Used as a fallback when pagedSQL(true) returned an empty page past offset 0:
// COUNT(*) OVER () emits no rows when the data SELECT is empty, so the
// caller would otherwise see total=0 even when the broader result set has
// matching rows. Wraps the inner query in `SELECT COUNT(*) FROM (...) sub`
// so any GROUP BY in the inner query is preserved (we count groups, matching
// what COUNT(*) OVER () would compute).
//
// Binds only p.args (FROM/WHERE/GROUP BY values). orderArgs are deliberately
// excluded — the count SQL has no ORDER BY clause to reference them, and
// passing extra bound values would fail with "bind message supplies N
// parameters, but prepared statement requires M".
func (p browseQueryPlan) countSQL() (string, []any) {
	args := append([]any{}, p.args...)
	sql := fmt.Sprintf(
		"SELECT COUNT(*) FROM (SELECT 1 FROM %s %s %s) sub",
		p.fromClause, p.whereClause, p.groupByClause,
	)
	return sql, args
}

// pagedSQL renders the final paged SELECT and returns it together with the
// fully-bound arg list. When includeTotal is true the SELECT list is appended
// with COUNT(*) OVER () AS total_count so the caller can read the total from
// the first scanned row in a single round trip. When includeTotal is false the
// caller has already requested a single-pass page, so we ask for one extra row
// to detect whether more pages exist without an exact count.
func (p browseQueryPlan) pagedSQL(includeTotal bool) (string, []any) {
	queryLimit := p.limit
	if !includeTotal {
		queryLimit++
	}
	// Bind order: where/from args, then order-by args, then LIMIT, then OFFSET.
	// limitArgIdx is computed by buildBrowsePlan after consuming order args, so
	// it correctly points at LIMIT after the orderArgs are bound below.
	args := append([]any{}, p.args...)
	args = append(args, p.orderArgs...)
	args = append(args, queryLimit, p.offset)
	offsetArgIdx := p.limitArgIdx + 1

	selectList := p.selectClause
	if includeTotal {
		selectList += ", COUNT(*) OVER () AS total_count"
	}
	sql := fmt.Sprintf(
		"SELECT %s FROM %s %s %s %s LIMIT $%d OFFSET $%d",
		selectList, p.fromClause, p.whereClause, p.groupByClause, p.orderBy,
		p.limitArgIdx, offsetArgIdx,
	)
	return sql, args
}

// buildBrowsePlan assembles the WHERE clause, FROM clause, args, ORDER BY, and
// GROUP BY for a browse query. It performs no I/O. browse() uses it to run the
// actual query; tests use it to assert the emitted SQL. earlyEmpty == true
// means the filters are unsatisfiable (e.g. empty library allowlist) and the
// caller should return an empty result without executing.
func (r *BrowseRepository) buildBrowsePlan(filters BrowseFilters) (browseQueryPlan, bool, error) {
	// Normalize defaults.
	if filters.Limit <= 0 {
		filters.Limit = 20
	}
	if filters.Limit > 100 {
		filters.Limit = 100
	}
	if filters.Offset < 0 {
		filters.Offset = 0
	}
	if filters.Order == "" {
		filters.Order = "desc"
	}
	if filters.Sort == "" {
		filters.Sort = "created_at"
	}

	// Build WHERE clause and args.
	var conditions []string
	var args []any
	argIdx := 1

	// Type filter (supports comma-separated multi-type, e.g. "movie,series").
	if filters.Type != "" {
		types := splitTypes(filters.Type)
		if len(types) == 1 {
			conditions = append(conditions, fmt.Sprintf("mi.type = $%d", argIdx))
			args = append(args, types[0])
			argIdx++
		} else {
			conditions = append(conditions, fmt.Sprintf("mi.type = ANY($%d)", argIdx))
			args = append(args, types)
			argIdx++
		}
	}

	if filters.ContentIDs != nil {
		if len(filters.ContentIDs) == 0 {
			return browseQueryPlan{}, true, nil
		}
		conditions = append(conditions, fmt.Sprintf("mi.content_id = ANY($%d)", argIdx))
		args = append(args, filters.ContentIDs)
		argIdx++
	}

	// Genre filter (GIN array containment).
	if filters.Genre != "" {
		conditions = append(conditions, fmt.Sprintf("mi.genres @> ARRAY[$%d]::text[]", argIdx))
		args = append(args, filters.Genre)
		argIdx++
	}

	if prefix := strings.TrimSpace(filters.NamePrefix); prefix != "" {
		// Dual-column OR so titles without a curated sort_title still match.
		// First arm matches the idx_media_items_sort_key expression
		// (LOWER(COALESCE(NULLIF(BTRIM(sort_title),''), title))) so the
		// anchored LIKE is sargable; second arm uses idx_media_items_search_exact_title
		// (LOWER(title)). Both arms are equivalent when sort_title is empty,
		// which is harmless — the planner can BitmapOr the two index scans.
		conditions = append(conditions, fmt.Sprintf(
			"(LOWER(COALESCE(NULLIF(BTRIM(mi.sort_title), ''), mi.title)) LIKE $%d ESCAPE '\\' OR LOWER(mi.title) LIKE $%d ESCAPE '\\')",
			argIdx, argIdx,
		))
		args = append(args, likePrefixPattern(prefix))
		argIdx++
	}

	// Year range filters.
	if filters.YearMin > 0 {
		conditions = append(conditions, fmt.Sprintf("mi.year >= $%d", argIdx))
		args = append(args, filters.YearMin)
		argIdx++
	}
	if filters.YearMax > 0 {
		conditions = append(conditions, fmt.Sprintf("mi.year <= $%d", argIdx))
		args = append(args, filters.YearMax)
		argIdx++
	}

	// Content rating filter (multi-value).
	if len(filters.ContentRating) > 0 {
		conditions = append(conditions, fmt.Sprintf("mi.content_rating = ANY($%d)", argIdx))
		args = append(args, filters.ContentRating)
		argIdx++
	}

	// Status filter.
	if filters.Status != "" {
		conditions = append(conditions, fmt.Sprintf("mi.status = $%d", argIdx))
		args = append(args, filters.Status)
		argIdx++
	}

	// Library access control: restrict to user's accessible libraries.
	needsLibJoin := filters.LibraryID > 0 || filters.LibraryIDs != nil || len(filters.DisabledLibraryIDs) > 0 || filters.Sort == "recently_added"
	needsPersonJoin := filters.PersonID > 0
	// When filtering by exactly one library and no person join, each
	// content_id matches at most one mil row, so the GROUP BY usually added
	// to dedup the junction join is unnecessary. Skipping it lets ORDER BY
	// mil.first_seen_at exploit idx_item_libraries_folder_seen_content
	// directly — turning a full-library scan + heapsort into a top-N index
	// walk.
	singleLibraryNoDedup := filters.LibraryID > 0 && filters.LibraryIDs == nil && len(filters.DisabledLibraryIDs) == 0 && !needsPersonJoin

	if filters.PersonID > 0 {
		conditions = append(conditions, fmt.Sprintf("ip.person_id = $%d", argIdx))
		args = append(args, filters.PersonID)
		argIdx++
	}

	if filters.LibraryID > 0 {
		conditions = append(conditions, fmt.Sprintf("mil.media_folder_id = $%d", argIdx))
		args = append(args, filters.LibraryID)
		argIdx++
	}

	if filters.LibraryIDs != nil {
		if len(filters.LibraryIDs) == 0 {
			// User has empty library access — return no results.
			return browseQueryPlan{}, true, nil
		}
		conditions = append(conditions, fmt.Sprintf("mil.media_folder_id = ANY($%d)", argIdx))
		args = append(args, filters.LibraryIDs)
		argIdx++
	}

	if len(filters.DisabledLibraryIDs) > 0 {
		conditions = append(conditions, fmt.Sprintf("NOT (mil.media_folder_id = ANY($%d))", argIdx))
		args = append(args, filters.DisabledLibraryIDs)
		argIdx++
	}

	applyAccessFilter("mi", AccessFilter{MaxContentRating: filters.MaxContentRating}, &conditions, &args, &argIdx)

	if filters.SnapshotAt != nil {
		conditions = append(conditions, fmt.Sprintf("mi.created_at <= $%d", argIdx))
		args = append(args, *filters.SnapshotAt)
		argIdx++
	}

	// Build FROM clause with optional JOIN.
	fromClause := "media_items mi"
	if needsLibJoin {
		fromClause = "media_items mi JOIN media_item_libraries mil ON mi.content_id = mil.content_id"
	}
	if needsPersonJoin {
		fromClause += " JOIN item_people ip ON ip.content_id = mi.content_id"
	}

	// Build WHERE string.
	whereClause := ""
	if len(conditions) > 0 {
		whereClause = "WHERE " + strings.Join(conditions, " AND ")
	}

	// Build ORDER BY clause. orderArgs are kept out of `args` so countSQL can
	// bind only its FROM/WHERE/GROUP BY values; pagedSQL binds them together.
	// argIdx still advances past them so limitArgIdx points at the right
	// LIMIT placeholder once orderArgs are bound positionally before LIMIT.
	orderBy, orderArgs := buildOrderByPlan(filters.Sort, filters.Order, filters.SnapshotAt, argIdx, singleLibraryNoDedup)
	argIdx += len(orderArgs)

	selectClause := browseItemColumns("mi")
	groupByClause := ""
	switch {
	case singleLibraryNoDedup:
		// Single library, no person join: mil row is unique per content_id.
		// Project mil.first_seen_at directly so ORDER BY can use the index.
		selectClause += ", mil.first_seen_at"
	case needsLibJoin:
		// Multi-library or disabled-library filter: dedup with GROUP BY and
		// expose the earliest first_seen_at as the "added at" timestamp.
		selectClause += ", MIN(mil.first_seen_at)"
		groupByClause = "GROUP BY " + browseGroupByColumns("mi")
	case needsPersonJoin:
		// Person join needs GROUP BY to deduplicate, but mil is not available.
		selectClause += ", mi.created_at"
		groupByClause = "GROUP BY " + browseGroupByColumns("mi")
	default:
		// No junction join — use created_at as the added_at fallback.
		selectClause += ", mi.created_at"
	}

	return browseQueryPlan{
		selectClause:  selectClause,
		fromClause:    fromClause,
		whereClause:   whereClause,
		groupByClause: groupByClause,
		orderBy:       orderBy,
		args:          args,
		orderArgs:     orderArgs,
		limit:         filters.Limit,
		offset:        filters.Offset,
		limitArgIdx:   argIdx,
	}, false, nil
}

// filterWhereClause builds the common WHERE clause and FROM clause used by the
// ListXxx distinct-value methods.  If the returned earlyEmpty flag is true the
// caller should return an empty result immediately (e.g. when LibraryIDs is an
// empty slice).
func filterWhereClause(filters BrowseFilters) (fromClause, whereClause string, args []any, earlyEmpty bool) {
	return filterWhereClauseForSource(filters, "media_items mi", "")
}

func filterWhereClauseForSource(filters BrowseFilters, baseRelation string, mediaScope string) (fromClause, whereClause string, args []any, earlyEmpty bool) {
	var conditions []string
	argIdx := 1

	if filters.Type != "" {
		types := splitTypes(filters.Type)
		if len(types) == 1 {
			conditions = append(conditions, fmt.Sprintf("mi.type = $%d", argIdx))
			args = append(args, types[0])
			argIdx++
		} else {
			conditions = append(conditions, fmt.Sprintf("mi.type = ANY($%d)", argIdx))
			args = append(args, types)
			argIdx++
		}
	}
	if prefix := strings.TrimSpace(filters.NamePrefix); prefix != "" {
		// Same dual-column shape as filterWhereClauseForSource's primary
		// browse path — see comment there for index-alignment rationale.
		conditions = append(conditions, fmt.Sprintf(
			"(LOWER(COALESCE(NULLIF(BTRIM(mi.sort_title), ''), mi.title)) LIKE $%d ESCAPE '\\' OR LOWER(mi.title) LIKE $%d ESCAPE '\\')",
			argIdx, argIdx,
		))
		args = append(args, likePrefixPattern(prefix))
		argIdx++
	}
	if filters.Status != "" {
		conditions = append(conditions, fmt.Sprintf("mi.status = $%d", argIdx))
		args = append(args, filters.Status)
		argIdx++
	}
	if filters.PersonID > 0 {
		conditions = append(conditions, fmt.Sprintf("ip.person_id = $%d", argIdx))
		args = append(args, filters.PersonID)
		argIdx++
	}
	if filters.LibraryID > 0 {
		conditions = append(conditions, fmt.Sprintf("mil.media_folder_id = $%d", argIdx))
		args = append(args, filters.LibraryID)
		argIdx++
	}
	if filters.ContentIDs != nil {
		if len(filters.ContentIDs) == 0 {
			return "", "", nil, true
		}
		conditions = append(conditions, fmt.Sprintf("mi.content_id = ANY($%d)", argIdx))
		args = append(args, filters.ContentIDs)
		argIdx++
	}
	if filters.LibraryIDs != nil {
		if len(filters.LibraryIDs) == 0 {
			return "", "", nil, true
		}
		conditions = append(conditions, fmt.Sprintf("mil.media_folder_id = ANY($%d)", argIdx))
		args = append(args, filters.LibraryIDs)
		argIdx++
	}

	if len(filters.DisabledLibraryIDs) > 0 {
		conditions = append(conditions, fmt.Sprintf("NOT (mil.media_folder_id = ANY($%d))", argIdx))
		args = append(args, filters.DisabledLibraryIDs)
		argIdx++
	}

	applyAccessFilter("mi", AccessFilter{MaxContentRating: filters.MaxContentRating}, &conditions, &args, &argIdx)

	fromClause = baseRelation
	libraryContentExpr := catalogLibraryContentExprForScope(mediaScope, "mi")
	if filters.LibraryID > 0 || filters.LibraryIDs != nil || len(filters.DisabledLibraryIDs) > 0 {
		membershipTable, membershipKey := catalogLibraryMembershipTableAndKeyForScope(mediaScope)
		fromClause += " JOIN " + membershipTable + " mil ON " + libraryContentExpr + " = mil." + membershipKey
	}
	if filters.PersonID > 0 {
		fromClause += " JOIN item_people ip ON ip.content_id = mi.content_id"
	}

	if len(conditions) > 0 {
		whereClause = "WHERE " + strings.Join(conditions, " AND ")
	}
	return fromClause, whereClause, args, false
}

// listDistinctArrayColumn returns sorted distinct non-empty values from an
// array column (genres, studios, networks, countries).
func (r *BrowseRepository) listDistinctArrayColumn(ctx context.Context, column string, filters BrowseFilters) ([]string, error) {
	return listDistinctArrayColumnWithSource(ctx, r.pool, column, filters, "media_items mi", "")
}

func listDistinctArrayColumnWithSource(
	ctx context.Context,
	pool *pgxpool.Pool,
	column string,
	filters BrowseFilters,
	baseRelation string,
	mediaScope string,
) ([]string, error) {
	fromClause, whereClause, args, empty := filterWhereClauseForSource(filters, baseRelation, mediaScope)
	if empty {
		return []string{}, nil
	}

	query := fmt.Sprintf(`
		SELECT DISTINCT val
		FROM (
			SELECT UNNEST(mi.%s) AS val
			FROM %s
			%s
		) vals
		WHERE val <> ''
		ORDER BY val ASC
	`, column, fromClause, whereClause)

	rows, err := pool.Query(ctx, query, args...)
	if err != nil {
		return nil, fmt.Errorf("listing %s: %w", column, err)
	}
	defer rows.Close()

	values := make([]string, 0)
	for rows.Next() {
		var v string
		if err := rows.Scan(&v); err != nil {
			return nil, fmt.Errorf("scan %s: %w", column, err)
		}
		v = strings.TrimSpace(v)
		if v == "" {
			continue
		}
		values = append(values, v)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate %s: %w", column, err)
	}

	slices.Sort(values)
	return values, nil
}

// listDistinctScalarColumn returns sorted distinct non-empty values from a
// scalar text column (e.g. content_rating).
func (r *BrowseRepository) listDistinctScalarColumn(ctx context.Context, column string, filters BrowseFilters) ([]string, error) {
	return listDistinctScalarColumnWithSource(ctx, r.pool, column, filters, "media_items mi", "")
}

func listDistinctScalarColumnWithSource(
	ctx context.Context,
	pool *pgxpool.Pool,
	column string,
	filters BrowseFilters,
	baseRelation string,
	mediaScope string,
) ([]string, error) {
	fromClause, whereClause, args, empty := filterWhereClauseForSource(filters, baseRelation, mediaScope)
	if empty {
		return []string{}, nil
	}

	query := fmt.Sprintf(`
		SELECT DISTINCT mi.%s
		FROM %s
		%s
		  AND mi.%s <> ''
		ORDER BY mi.%s ASC
	`, column, fromClause, whereClause, column, column)

	// When there are no WHERE conditions, the extra AND is invalid — prepend WHERE instead.
	if whereClause == "" {
		query = fmt.Sprintf(`
			SELECT DISTINCT mi.%s
			FROM %s
			WHERE mi.%s <> ''
			ORDER BY mi.%s ASC
		`, column, fromClause, column, column)
	}

	rows, err := pool.Query(ctx, query, args...)
	if err != nil {
		return nil, fmt.Errorf("listing %s: %w", column, err)
	}
	defer rows.Close()

	values := make([]string, 0)
	for rows.Next() {
		var v string
		if err := rows.Scan(&v); err != nil {
			return nil, fmt.Errorf("scan %s: %w", column, err)
		}
		v = strings.TrimSpace(v)
		if v == "" {
			continue
		}
		values = append(values, v)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate %s: %w", column, err)
	}

	slices.Sort(values)
	return values, nil
}

// ListGenres returns the distinct genres matching the supplied browse filters.
func (r *BrowseRepository) ListGenres(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctArrayColumn(ctx, "genres", filters)
}

// ListStudios returns the distinct studios matching the supplied browse filters.
func (r *BrowseRepository) ListStudios(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctArrayColumn(ctx, "studios", filters)
}

// ListNetworks returns the distinct networks matching the supplied browse filters.
func (r *BrowseRepository) ListNetworks(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctArrayColumn(ctx, "networks", filters)
}

// ListCountries returns the distinct countries matching the supplied browse filters.
func (r *BrowseRepository) ListCountries(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctArrayColumn(ctx, "countries", filters)
}

// ListContentRatings returns the distinct content ratings matching the supplied browse filters.
func (r *BrowseRepository) ListContentRatings(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctScalarColumn(ctx, "content_rating", filters)
}

func (r *BrowseRepository) ListOriginalLanguages(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctScalarColumn(ctx, "original_language", filters)
}

func (r *BrowseRepository) ListResolutions(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return listResolutionsWithSource(ctx, r.pool, filters, "media_items mi", "")
}

func listResolutionsWithSource(
	ctx context.Context,
	pool *pgxpool.Pool,
	filters BrowseFilters,
	baseRelation string,
	mediaScope string,
) ([]string, error) {
	fromClause, whereClause, args, earlyEmpty := filterWhereClauseForSource(filters, baseRelation, mediaScope)
	if earlyEmpty {
		return nil, nil
	}
	mediaFileJoin := catalogMediaFileJoinConditionForScope(mediaScope, "mf", "mi")

	query := fmt.Sprintf(`
		SELECT DISTINCT mf.resolution
		FROM %s
		JOIN media_files mf ON %s
		%s
		  AND mf.missing_since IS NULL
		  AND mf.resolution IS NOT NULL
		  AND BTRIM(mf.resolution) <> ''
		ORDER BY mf.resolution ASC
	`, fromClause, mediaFileJoin, browseFilterPrefix(whereClause))
	return queryDistinctStrings(ctx, pool, query, args)
}

func (r *BrowseRepository) ListAudioLanguages(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return r.listDistinctJSONBLanguageWithFilters(ctx, "audio_tracks", filters)
}

func (r *BrowseRepository) ListSubtitleLanguages(ctx context.Context, filters BrowseFilters) ([]string, error) {
	return listSubtitleLanguagesWithSource(ctx, r.pool, filters, "media_items mi", "")
}

func listSubtitleLanguagesWithSource(
	ctx context.Context,
	pool *pgxpool.Pool,
	filters BrowseFilters,
	baseRelation string,
	mediaScope string,
) ([]string, error) {
	fromClause, whereClause, args, earlyEmpty := filterWhereClauseForSource(filters, baseRelation, mediaScope)
	if earlyEmpty {
		return nil, nil
	}
	mediaFileJoin := catalogMediaFileJoinConditionForScope(mediaScope, "mf", "mi")

	// Embedded subtitles use the migration 104 generated text[]
	// `subtitle_language_codes`; external subs still need a JSONB unnest
	// because the generated column only covers subtitle_tracks
	// (audit 2026-05-01 §2.5b).
	query := fmt.Sprintf(`
		SELECT DISTINCT value
		FROM (
			SELECT lang AS value
			FROM %s
			JOIN media_files mf ON %s
			CROSS JOIN LATERAL UNNEST(mf.subtitle_language_codes) AS lang
			%s
			  AND mf.missing_since IS NULL

			UNION

			SELECT LOWER(COALESCE(track->>'language', '')) AS value
			FROM %s
			JOIN media_files mf ON %s
			CROSS JOIN LATERAL jsonb_array_elements(COALESCE(mf.external_subtitles, '[]'::jsonb)) AS track
			%s
			  AND mf.missing_since IS NULL
		) languages
		WHERE value IS NOT NULL AND value <> ''
		ORDER BY value ASC
	`, fromClause, mediaFileJoin, browseFilterPrefix(whereClause), fromClause, mediaFileJoin, browseFilterPrefix(whereClause))
	return queryDistinctStrings(ctx, pool, query, args)
}

func (r *BrowseRepository) listDistinctJSONBLanguageWithFilters(ctx context.Context, column string, filters BrowseFilters) ([]string, error) {
	return listDistinctJSONBLanguageWithSource(ctx, r.pool, column, filters, "media_items mi", "")
}

func listDistinctJSONBLanguageWithSource(
	ctx context.Context,
	pool *pgxpool.Pool,
	column string,
	filters BrowseFilters,
	baseRelation string,
	mediaScope string,
) ([]string, error) {
	fromClause, whereClause, args, earlyEmpty := filterWhereClauseForSource(filters, baseRelation, mediaScope)
	if earlyEmpty {
		return nil, nil
	}
	mediaFileJoin := catalogMediaFileJoinConditionForScope(mediaScope, "mf", "mi")

	// Migration 104 added STORED text[] generated columns derived from the
	// JSONB tracks. Use them when available so this listing UNNESTs an
	// indexed array instead of parsing JSONB per row
	// (audit 2026-05-01 §2.5b).
	arrayColumn := generatedLanguageColumnFor(column)
	if arrayColumn != "" {
		query := fmt.Sprintf(`
			SELECT DISTINCT lang AS value
			FROM %s
			JOIN media_files mf ON %s
			CROSS JOIN LATERAL UNNEST(mf.%s) AS lang
			%s
			  AND mf.missing_since IS NULL
			  AND lang IS NOT NULL
			  AND lang <> ''
			ORDER BY value ASC
		`, fromClause, mediaFileJoin, arrayColumn, browseFilterPrefix(whereClause))
		return queryDistinctStrings(ctx, pool, query, args)
	}

	query := fmt.Sprintf(`
		SELECT DISTINCT LOWER(COALESCE(track->>'language', '')) AS value
		FROM %s
		JOIN media_files mf ON %s
		CROSS JOIN LATERAL jsonb_array_elements(COALESCE(mf.%s, '[]'::jsonb)) AS track
		%s
		  AND mf.missing_since IS NULL
		  AND COALESCE(track->>'language', '') <> ''
		ORDER BY value ASC
	`, fromClause, mediaFileJoin, column, browseFilterPrefix(whereClause))
	return queryDistinctStrings(ctx, pool, query, args)
}

// generatedLanguageColumnFor returns the migration-104 STORED text[] column
// that mirrors the given JSONB tracks column, or "" if none exists.
func generatedLanguageColumnFor(jsonbColumn string) string {
	switch jsonbColumn {
	case "audio_tracks":
		return "audio_language_codes"
	case "subtitle_tracks":
		return "subtitle_language_codes"
	default:
		return ""
	}
}

func browseFilterPrefix(whereClause string) string {
	if whereClause == "" {
		return "WHERE TRUE"
	}
	return whereClause
}

func queryDistinctStrings(ctx context.Context, pool *pgxpool.Pool, query string, args []any) ([]string, error) {
	rows, err := pool.Query(ctx, query, args...)
	if err != nil {
		return nil, err
	}
	defer rows.Close()

	values := make([]string, 0)
	for rows.Next() {
		var value string
		if err := rows.Scan(&value); err != nil {
			return nil, err
		}
		if strings.TrimSpace(value) == "" {
			continue
		}
		values = append(values, value)
	}
	if err := rows.Err(); err != nil {
		return nil, err
	}
	return values, nil
}

// browseItemColumns returns the item columns prefixed with the given alias.
func browseItemColumns(alias string) string {
	cols := []string{
		"content_id", "type", "title", "sort_title", "original_title", "year", "genres",
		"content_rating", "runtime", "overview", "tagline",
		"rating_imdb", "rating_tmdb", "rating_rt_critic", "rating_rt_audience",
		"imdb_id", "tmdb_id", "tvdb_id",
		"poster_path", "poster_thumbhash", "backdrop_path", "backdrop_thumbhash", "logo_path",
		"metadata_s3_path", "metadata_etag", "season_count",
		"studios", "networks", "countries", "keywords", "original_language", "release_date::text", "first_air_date", "last_air_date",
		"show_status",
		"matched_at", "episode_metadata_incomplete", "episode_metadata_last_checked_at", "status", "created_at", "updated_at",
	}
	prefixed := make([]string, len(cols))
	for i, col := range cols {
		if col == "last_air_date" {
			prefixed[i] = effectiveLastAirDateExpr(alias)
			continue
		}
		prefixed[i] = alias + "." + col
	}
	return strings.Join(prefixed, ", ")
}

// browseGroupByColumns returns the columns needed for GROUP BY when joining
// with the junction table.
func browseGroupByColumns(alias string) string {
	cols := []string{
		"content_id", "type", "title", "sort_title", "original_title", "year", "genres",
		"content_rating", "runtime", "overview", "tagline",
		"rating_imdb", "rating_tmdb", "rating_rt_critic", "rating_rt_audience",
		"imdb_id", "tmdb_id", "tvdb_id",
		"poster_path", "poster_thumbhash", "backdrop_path", "backdrop_thumbhash", "logo_path",
		"metadata_s3_path", "metadata_etag", "season_count",
		"studios", "networks", "countries", "keywords", "original_language", "release_date::text", "first_air_date", "last_air_date",
		"show_status",
		"matched_at", "episode_metadata_incomplete", "episode_metadata_last_checked_at", "status", "created_at", "updated_at",
	}
	prefixed := make([]string, len(cols))
	for i, col := range cols {
		prefixed[i] = alias + "." + col
	}
	return strings.Join(prefixed, ", ")
}

// likePrefixPattern returns prefix lowercased and LIKE-escaped (%, _, \) with
// a trailing % so it forms a prefix-anchored LIKE pattern. Thin wrapper over
// escapePrefixForLike so any future special-character fix applies to both
// the browse path and the query_executor preview path.
func likePrefixPattern(prefix string) string {
	return escapePrefixForLike(prefix) + "%"
}

// scanBrowseItems scans rows returned by the browse query, which include an
// extra added_at column appended after the standard item columns.
func scanBrowseItems(rows pgx.Rows) ([]*models.MediaItem, error) {
	var items []*models.MediaItem
	for rows.Next() {
		var item models.MediaItem
		err := rows.Scan(
			&item.ContentID,
			&item.Type,
			&item.Title,
			&item.SortTitle,
			&item.OriginalTitle,
			&item.Year,
			&item.Genres,
			&item.ContentRating,
			&item.Runtime,
			&item.Overview,
			&item.Tagline,
			&item.RatingIMDB,
			&item.RatingTMDB,
			&item.RatingRTCritic,
			&item.RatingRTAudience,
			&item.ImdbID,
			&item.TmdbID,
			&item.TvdbID,
			&item.PosterPath,
			&item.PosterThumbhash,
			&item.BackdropPath,
			&item.BackdropThumbhash,
			&item.LogoPath,
			&item.MetadataS3Path,
			&item.MetadataEtag,
			&item.SeasonCount,
			&item.Studios,
			&item.Networks,
			&item.Countries,
			&item.Keywords,
			&item.OriginalLanguage,
			&item.ReleaseDate,
			&item.FirstAirDate,
			&item.LastAirDate,
			&item.ShowStatus,
			&item.MatchedAt,
			&item.EpisodeMetadataIncomplete,
			&item.EpisodeMetadataLastCheckedAt,
			&item.Status,
			&item.CreatedAt,
			&item.UpdatedAt,
			&item.AddedAt,
		)
		if err != nil {
			return nil, fmt.Errorf("scanning browse item row: %w", err)
		}
		items = append(items, &item)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterating browse item rows: %w", err)
	}
	return items, nil
}

// scanBrowseItemsWithTotal scans rows that include a trailing total_count column
// emitted by COUNT(*) OVER (). Used by browse() in the includeTotal path so we
// don't fire a separate count query.
func scanBrowseItemsWithTotal(rows pgx.Rows) ([]*models.MediaItem, int, error) {
	var (
		items []*models.MediaItem
		total int
	)
	for rows.Next() {
		var item models.MediaItem
		var rowTotal int
		err := rows.Scan(
			&item.ContentID,
			&item.Type,
			&item.Title,
			&item.SortTitle,
			&item.OriginalTitle,
			&item.Year,
			&item.Genres,
			&item.ContentRating,
			&item.Runtime,
			&item.Overview,
			&item.Tagline,
			&item.RatingIMDB,
			&item.RatingTMDB,
			&item.RatingRTCritic,
			&item.RatingRTAudience,
			&item.ImdbID,
			&item.TmdbID,
			&item.TvdbID,
			&item.PosterPath,
			&item.PosterThumbhash,
			&item.BackdropPath,
			&item.BackdropThumbhash,
			&item.LogoPath,
			&item.MetadataS3Path,
			&item.MetadataEtag,
			&item.SeasonCount,
			&item.Studios,
			&item.Networks,
			&item.Countries,
			&item.Keywords,
			&item.OriginalLanguage,
			&item.ReleaseDate,
			&item.FirstAirDate,
			&item.LastAirDate,
			&item.ShowStatus,
			&item.MatchedAt,
			&item.EpisodeMetadataIncomplete,
			&item.EpisodeMetadataLastCheckedAt,
			&item.Status,
			&item.CreatedAt,
			&item.UpdatedAt,
			&item.AddedAt,
			&rowTotal,
		)
		if err != nil {
			return nil, 0, fmt.Errorf("scanning browse item row with total: %w", err)
		}
		items = append(items, &item)
		total = rowTotal
	}
	if err := rows.Err(); err != nil {
		return nil, 0, fmt.Errorf("iterating browse item rows: %w", err)
	}
	return items, total, nil
}

// buildOrderBy constructs the ORDER BY clause from sort and order parameters.
func buildOrderBy(sort, order string) string {
	clause, _ := buildOrderByPlan(sort, order, nil, 0, false)
	return clause
}

func buildOrderByPlan(sort, order string, snapshot *time.Time, argIdx int, singleLibraryNoDedup bool) (string, []any) {
	direction := "DESC"
	if strings.EqualFold(order, "asc") {
		direction = "ASC"
	}

	nullsClause := ""
	if direction == "DESC" {
		nullsClause = " NULLS LAST"
	}

	// Every case includes mi.content_id as a final tiebreaker so that
	// OFFSET-based pagination is deterministic when many rows share the
	// same sort value (e.g. same IMDB rating or NULL).
	switch sort {
	case "random":
		if snapshot != nil && argIdx > 0 {
			return fmt.Sprintf("ORDER BY md5(mi.content_id || $%d::text) ASC, mi.content_id ASC", argIdx), []any{snapshot.UTC().Format(time.RFC3339Nano)}
		}
		return "ORDER BY RANDOM()", nil
	case "release_date":
		return fmt.Sprintf(
			"ORDER BY COALESCE(mi.release_date::text, NULLIF(BTRIM(mi.first_air_date), '')) %s%s, mi.content_id ASC",
			direction,
			nullsClause,
		), nil
	case "last_air_date":
		return fmt.Sprintf(
			"ORDER BY %s %s%s, mi.content_id ASC",
			effectiveLastAirDateExpr("mi"),
			direction,
			nullsClause,
		), nil
	case "rating_imdb":
		return fmt.Sprintf("ORDER BY mi.rating_imdb %s%s, mi.content_id ASC", direction, nullsClause), nil
	case "rating_tmdb":
		return fmt.Sprintf("ORDER BY mi.rating_tmdb %s%s, mi.content_id ASC", direction, nullsClause), nil
	case "year":
		return fmt.Sprintf("ORDER BY mi.year %s, mi.content_id ASC", direction), nil
	case "title", "sort_title":
		return fmt.Sprintf(
			"ORDER BY LOWER(COALESCE(NULLIF(BTRIM(mi.sort_title), ''), mi.title)) %s, LOWER(mi.title) %s, mi.content_id ASC",
			direction,
			direction,
		), nil
	case "recently_added":
		// Without GROUP BY (single-library filter), reference mil.first_seen_at
		// directly so the planner can drive the order from
		// idx_item_libraries_folder_seen_content instead of materializing
		// every library row to aggregate.
		if singleLibraryNoDedup {
			return fmt.Sprintf("ORDER BY mil.first_seen_at %s, mi.content_id ASC", direction), nil
		}
		return fmt.Sprintf("ORDER BY MIN(mil.first_seen_at) %s, mi.content_id ASC", direction), nil
	case "created_at":
		return fmt.Sprintf("ORDER BY mi.created_at %s, mi.content_id ASC", direction), nil
	default:
		return fmt.Sprintf("ORDER BY mi.created_at %s, mi.content_id ASC", direction), nil
	}
}

// ParseContentRatings splits a comma-separated content rating string into
// a slice. Empty input returns nil.
func ParseContentRatings(s string) []string {
	if s == "" {
		return nil
	}
	parts := strings.Split(s, ",")
	ratings := make([]string, 0, len(parts))
	for _, p := range parts {
		trimmed := strings.TrimSpace(p)
		if trimmed != "" {
			ratings = append(ratings, trimmed)
		}
	}
	if len(ratings) == 0 {
		return nil
	}
	return ratings
}

// ParseIntParam parses a string as int, returning 0 if empty or invalid.
func ParseIntParam(s string) int {
	if s == "" {
		return 0
	}
	v, _ := strconv.Atoi(s)
	return v
}

// ParseInt64Param parses a string to int64, returning 0 if empty or invalid.
func ParseInt64Param(s string) int64 {
	if s == "" {
		return 0
	}
	v, _ := strconv.ParseInt(s, 10, 64)
	return v
}

// splitTypes splits a comma-separated type string into trimmed, non-empty parts.
func splitTypes(s string) []string {
	parts := strings.Split(s, ",")
	result := make([]string, 0, len(parts))
	for _, p := range parts {
		if t := strings.TrimSpace(p); t != "" {
			result = append(result, t)
		}
	}
	return result
}