jellybit/internal/metadata/metadata.go

// Package metadata — интерфейс баз метаданных и клиенты TMDB/TVDB.
//
// Базы опциональны (включаются конфигом). Их роль — подтвердить распознавание
// официальным id и каноническим именем: при единичном сильном матче по
// названию+году раскладка делается автоматически, иначе уходит в review
// (см. docs/specs/recognition.md → «Модель уверенности»). Каждый клиент
// ходит наружу через опциональный HTTP-прокси с таймаутом.
package metadata

import "context"

// MediaType — вид контента в запросе к базе.
type MediaType string

const (
	Movie  MediaType = "movie"
	Series MediaType = "series"
)

// Query — запрос поиска в базе.
type Query struct {
	Type  MediaType
	Title string // каноническое название или provider_hint
	Year  int    // 0 — без ограничения по году
}

// Candidate — результат поиска: официальный id и каноническое имя.
//
// ID — нативный id провайдера (по нему запрашиваются SeasonEpisodeCounts).
// TagProvider/TagID — опц. внешний id для имени папки Jellyfin: напр. TVMaze
// ищет без ключа, но отдаёт TVDB/IMDb-id во внешних ссылках, и тег ставим
// привычный ([tvdbid-…]). Пусто → тег берётся из Provider/ID.
type Candidate struct {
	Provider      string // "tmdb" | "tvdb" | "tvmaze"
	ID            string
	Title         string
	OriginalTitle string
	Year          int
	URL           string // ссылка на страницу элемента на сайте провайдера
	TagProvider   string // напр. "tvdb"/"imdb" (опц.)
	TagID         string
}

// Provider — одна база метаданных.
type Provider interface {
	// Name — идентификатор провайдера ("tmdb"/"tvdb"), он же префикс тега.
	Name() string
	// Search ищет кандидатов по названию (и году, если задан).
	Search(ctx context.Context, q Query) ([]Candidate, error)
	// SeasonEpisodeCounts возвращает число серий по сезонам для сериала
	// (ключ — номер сезона). Нужен для валидации полноты сезон-пака.
	SeasonEpisodeCounts(ctx context.Context, id string) (map[int]int, error)
}