plugin

type AudioChannels string

type AudioCodec string

type Capabilities struct {
	SearchAvailable   bool
	TVSearchAvailable bool
	MovieSearch       bool
	Categories        []int // Newznab/Torznab category IDs
}

type Codec string

type DownloadClient interface {
	Name() string
	Protocol() Protocol

	// Add submits a release to the download client.
	// Returns the client-assigned item ID for future status queries.
	Add(ctx context.Context, r Release) (clientItemID string, err error)

	// Status returns the current state of a download client item.
	Status(ctx context.Context, clientItemID string) (QueueItem, error)

	// GetQueue returns all items currently in the download client.
	GetQueue(ctx context.Context) ([]QueueItem, error)

	// Remove deletes an item from the download client.
	// If deleteFiles is true, the downloaded data is also deleted.
	Remove(ctx context.Context, clientItemID string, deleteFiles bool) error

	// Test validates that the connection to the download client works.
	Test(ctx context.Context) error
}

type DownloadStatus string

type EventType string

type HDRFormat string

type ImportList interface {
	Name() string
	Fetch(ctx context.Context) ([]ImportListItem, error)
	Test(ctx context.Context) error
}

type ImportListItem struct {
	TMDbID     int    // required — canonical identifier
	IMDbID     string // optional; used for display/logging
	Title      string
	Year       int
	PosterPath string // optional; TMDb poster path (e.g. "/abc123.jpg")
}

type Indexer interface {
	// Name returns the human-readable plugin name, e.g. "Torznab".
	Name() string

	// Protocol returns the release download mechanism this indexer provides.
	Protocol() Protocol

	// Capabilities returns what search types this indexer supports.
	Capabilities(ctx context.Context) (Capabilities, error)

	// Search queries the indexer for releases matching the query.
	Search(ctx context.Context, q SearchQuery) ([]Release, error)

	// GetRecent returns the most recent releases from the indexer's RSS feed.
	GetRecent(ctx context.Context) ([]Release, error)

	// Test validates that the indexer is reachable and configured correctly.
	Test(ctx context.Context) error
}

type IndexerFlag string

type MediaServer interface {
	// Name returns the human-readable name of the media server plugin.
	Name() string

	// RefreshLibrary tells the media server to re-scan the library section
	// that contains seriesPath. Implementations may fall back to a full
	// library refresh if path-scoped scanning is unavailable.
	RefreshLibrary(ctx context.Context, seriesPath string) error

	// Test verifies that the media server is reachable and the credentials
	// are valid.
	Test(ctx context.Context) error
}

type NotificationEvent struct {
	Type      EventType
	Timestamp time.Time
	SeriesID  string         // UUID, if series-related; empty otherwise
	Message   string         // human-readable summary
	Data      map[string]any // event-specific extra fields
}

type Notifier interface {
	Name() string
	Notify(ctx context.Context, event NotificationEvent) error
	Test(ctx context.Context) error
}

type Protocol string

type Quality struct {
	Resolution    Resolution    `json:"resolution"`
	Source        Source        `json:"source"`
	Codec         Codec         `json:"codec"`
	HDR           HDRFormat     `json:"hdr"`
	AudioCodec    AudioCodec    `json:"audio_codec,omitempty"`
	AudioChannels AudioChannels `json:"audio_channels,omitempty"`
	// Name is the human-readable label derived from the video fields,
	// e.g. "Bluray-1080p x265" or "WEBDL-2160p HDR10".
	Name string `json:"name"`
}

type QueueItem struct {
	ClientItemID string
	Title        string
	Status       DownloadStatus
	Size         int64
	Downloaded   int64
	SeedRatio    float64 // torrent only; 0 for NZB
	Error        string
	// ContentPath is the absolute filesystem path to the downloaded content.
	// For single-file downloads this is the file path; for multi-file downloads
	// it is the root directory. Empty until the download client reports it.
	ContentPath string
	// AddedAt is the Unix timestamp when the item was added to the client.
	// Zero if the client does not report this field.
	AddedAt int64
}

type Release struct {
	GUID         string
	Title        string
	Indexer      string
	Protocol     Protocol
	DownloadURL  string
	InfoURL      string
	Size         int64
	Seeds        int
	Peers        int
	AgeDays      float64
	Quality      Quality
	Edition      string // canonical edition name parsed from title; empty = untagged
	ReleaseGroup string // scene group name parsed from title; empty = unknown
	IndexerFlags []IndexerFlag

	// Media context — populated by Pilot/Prism before sending to download client.
	// Download clients that support renaming (Haul) use these fields.
	MediaType     string `json:"media_type,omitempty"`     // "movie" or "tv"
	MediaTitle    string `json:"media_title,omitempty"`    // series or movie title
	MediaYear     int    `json:"media_year,omitempty"`     // release year
	SeasonNumber  int    `json:"season_number,omitempty"`  // TV only
	EpisodeNumber int    `json:"episode_number,omitempty"` // TV only
	EpisodeTitle  string `json:"episode_title,omitempty"`  // TV only

	// Arr-side IDs forwarded to history-aware download clients (Haul)
	// so they can answer "have I downloaded anything for series X?"
	// later. All optional; leaving empty disables the lookup integration
	// for this grab.
	TMDBID    int    `json:"tmdb_id,omitempty"`    // TMDB tv/movie id
	SeriesID  string `json:"series_id,omitempty"`  // Pilot series UUID
	EpisodeID string `json:"episode_id,omitempty"` // Pilot episode UUID
}

type Resolution string

type ScoreBreakdown struct {
	Total      int              `json:"total"`
	Dimensions []ScoreDimension `json:"dimensions"`
	// CustomFormatScore is the sum of matched custom format scores for the
	// quality profile. It sits alongside (not inside) Total because CF scoring
	// is an independent dimension used for separate thresholds.
	CustomFormatScore int      `json:"custom_format_score"`
	MatchedFormats    []string `json:"matched_formats,omitempty"`
	// EditionBonus is the bonus points awarded when the release edition
	// matches the series' preferred edition (+30 pts). It is additive
	// to Total and reflected in the Dimensions list.
	EditionBonus int `json:"edition_bonus"`
}

type ScoreDimension struct {
	Name    string `json:"name"`    // "resolution", "source", "codec", "hdr"
	Score   int    `json:"score"`   // points awarded for this dimension
	Max     int    `json:"max"`     // maximum possible for this dimension
	Matched bool   `json:"matched"` // did it meet the profile requirement?
	Got     string `json:"got"`     // what we found (e.g. "x264")
	Want    string `json:"want"`    // what the profile requires (e.g. "x265")
}

type SearchQuery struct {
	Query   string // free-text query, e.g. "Breaking Bad S01E05"
	TVDBID  int    // TVDB ID when available
	TMDBID  int    // TMDB ID when available
	IMDBID  string // e.g. "tt0903747"
	Year    int
	Season  int // season number for TV episode filtering
	Episode int // episode number for TV episode filtering
}

type SeedLimiter interface {
	SetSeedLimits(ctx context.Context, clientItemID string, ratioLimit float64, seedTimeSecs int) error
}

type Source string

type TMDBInjectable interface {
	SetTMDBClient(client any)
}

type TraktInjectable interface {
	SetTraktClient(client any)
}

type WatchEvent struct {
	TMDBID    int       // series identifier
	Title     string    // for display/logging
	WatchedAt time.Time // when playback completed
	UserName  string    // media server user (for multi-user setups)
}

type WatchProvider interface {
	// WatchHistory returns watch events since the given timestamp.
	// Each event represents one completed playback (>= 90% watched).
	WatchHistory(ctx context.Context, since time.Time) ([]WatchEvent, error)
}