experience

type AccessPolicy interface {
	Allowed(*core.User, *core.Title) bool
}

type AdditionalRows struct {
	Playlists  PlaylistRowSource
	Watchlist  DiscoveryRowSource
	Personal   DiscoveryRowSource
	Live       LiveGuideSource
	Visibility Visibility
	Restricted func(*core.User) bool
	Now        func() time.Time
}

type CandidateComposer struct {
	Ranker     CandidateRanker
	Resume     ResumeCandidates
	Libraries  []Library
	Visibility Visibility
	Restricted func(*core.User) bool
}

type CandidateRanker interface {
	Home(context.Context, *core.User, core.HomeSituation, int, func(context.Context, *core.User, *core.Title) bool) ([]RankedCandidate, error)
	Library(context.Context, *core.User, core.MediaType, core.HomeSituation, int, func(context.Context, *core.User, *core.Title) bool) ([]RankedCandidate, error)
}

type CandidateRowSource struct {
	Load       func(context.Context, frontend.RowRequest) ([]RankedCandidate, error)
	Additional func(context.Context, frontend.RowRequest) ([]frontend.Row, error)
	Kind       func(string) string
}

type CinemaCandidate struct {
	Title   core.Title
	Extras  []frontend.Extra
	Watched bool
}

type Continue struct {
	Filter       func(context.Context, *core.User, []core.Title) []core.Title
	State        core.State
	EpisodeOrder interface {
		Grouped(context.Context, *core.User, []core.RatingKey) (map[core.RatingKey]bool, error)
	}
	Now                func() time.Time
	Grandchildren      func(context.Context, core.RatingKey) ([]core.Title, error)
	NextEpisode        func(context.Context, core.RatingKey) (*core.Title, error)
	Visible            func(context.Context, *core.User, *core.Title) bool
	SameDayUnavailable func(context.Context, *core.Title) bool
	GetTitles          func(context.Context, []core.RatingKey) []core.Title
	SectionAllowed     func(*core.User, core.MediaType) bool
	OnError            func(error)
	FavoriteShows      func(context.Context, *core.User) (map[core.RatingKey]bool, error)
	// Unrestricted is a trusted policy capability; nil fails closed. It is
	// supplied only when the catalogue and policy authorize the legacy path.
	Unrestricted func(*core.User) bool
}

type DetailRelated struct {
	Source     core.Recommender
	Visibility Visibility
	Get        func(context.Context, core.RatingKey) (*core.Title, error)
}

type DiscoveryCandidate struct {
	Index   int
	Purpose core.RowPurpose
	Items   []core.Title
}

type DiscoveryRowSource interface {
	Rows(context.Context, *core.User, int) ([]RankedCandidate, error)
}

type DiscoverySelection struct {
	Visibility   Visibility
	Unrestricted func(*core.User) bool
}

type EstimatePlanner interface {
	Plan(context.Context, frontend.PlanRequest) (frontend.PlayPlan, error)
}

type ExtrasSource interface {
	Enabled() bool
	List(context.Context, *core.Title, string) ([]extras.Extra, error)
}

type FavoriteKind string

type FavoriteSources struct {
	Title      func(context.Context, core.RatingKey) (*core.Title, error)
	Collection func(context.Context, *core.User, core.RatingKey) (*core.Collection, error)
	// ChannelAllowed checks one channel. It is the live-TV path; title,
	// person, and collection decisions must not call it.
	ChannelAllowed func(context.Context, *core.User, string) (bool, error)
	// ChannelIDs lists every allowed channel. ChannelAllowed replaces it.
	ChannelIDs func(context.Context, *core.User) ([]string, error)
	PersonPage func(context.Context, int64, int, int) ([]core.Title, error)
}

type FavoriteSubject struct {
	Kind FavoriteKind
	ID   string
}

type FirstObservedLedger struct {
	// contains filtered or unexported fields
}

type HomeAssembly[P any] struct {
	Render      func(core.Hub) P
	Identity    func(P) string
	Report      func(P) (core.Hub, core.NeutralHomeRow)
	Continue    func() (core.Hub, P)
	Playlists   func() (P, bool)
	Discovery   func() []core.Hub
	Live        func() (P, bool)
	InLibraries func(core.Hub) bool
	Keep        func(P) bool
	Layout      func([]P, []core.Hub, []core.NeutralHomeRow) []P
}

type HomeCandidate struct {
	Index       int
	Purpose     core.RowPurpose
	Promoted    bool
	InLibraries bool
}

type HomeSelection struct {
	Source     core.Recommender
	Visibility Visibility
	Restricted bool
}

type LayoutCandidate struct {
	ID        string
	Title     string
	Type      core.MediaType
	Purpose   core.RowPurpose
	ItemCount int
}

type Library struct {
	ID   int
	Name string
	Type core.MediaType
	// Virtual is true only when the host asserts this library has no physical
	// locations. False means the host did not assert virtual origin.
	Virtual bool
}

type LibraryPageExclusions struct {
	Keys                           []core.RatingKey
	ExcludeGenres, ExcludeKeywords []string
	MaxContentRating               string
	Movie, Television              core.Filter
}

type LiveGuideSource interface {
	AllowedChannels(context.Context, *core.User) ([]livetv.Channel, error)
	Guide(context.Context, *core.User, time.Time, time.Time) ([]livetv.Programme, error)
}

type MarkerSource interface {
	CachedMarkers(context.Context, core.RatingKey, core.MediaInfo) ([]markers.Marker, error)
}

type PeopleRead struct {
	Viewer          *core.User
	SectionFor      func(core.MediaType) (int, bool)
	Policy          AccessPolicy
	FilterAvailable func(context.Context, []core.Title) []core.Title
	Titles          func(context.Context, []core.RatingKey) (map[core.RatingKey]core.Title, error)
	Finish          func(context.Context) error
	Close           func()
}

type PersonCandidate struct {
	TMDB int64
	Name string
}

type PlaylistRowSource interface {
	List(context.Context, int64) ([]core.Playlist, error)
}

type PlaylistSelection struct {
	Playlists     core.Playlists
	Collections   core.Collections
	Visibility    Visibility
	Children      func(context.Context, core.RatingKey) ([]core.Title, error)
	Grandchildren func(context.Context, core.RatingKey) ([]core.Title, error)
}

type PlexIssuedIdentity struct {
	Audio            *core.StreamInfo
	AudioPosition    int
	AudioSet         bool
	Subtitle         *core.StreamInfo
	SubtitlePosition int
	SubtitleSet      bool
}

type PostPlayRow struct {
	Purpose core.RowPurpose
	Items   []core.Title
}

type PostPlaySelection struct {
	Visibility   Visibility
	Unrestricted bool
	Picks        func(context.Context, int) []core.PostPlayPick
	Related      func(context.Context, int) ([]core.Hub, error)
}

type PreviewRows struct {
	Availability func(context.Context, int) []core.Hub
	Filter       func(context.Context, *core.User, []core.Title) ([]core.Title, error)
	Watchlist    func(context.Context, *core.User, int) ([]core.Hub, error)
	Personal     func(context.Context, *core.User, int) ([]core.Hub, error)
	Live         func(context.Context, *core.User, int) (core.Hub, error)
	LiveEnabled  func() bool
}

type RankedCandidate struct {
	ID        string
	Purpose   core.RowPurpose
	Title     string
	Type      core.MediaType
	Style     string
	Promoted  bool
	Items     []core.Title
	More      bool
	Key       core.RatingKey
	ItemCount int
}

type ReceiptOptions struct {
	DB            *sql.DB
	Active        func(context.Context, int64) (*core.User, error)
	Allowed       func(context.Context, *core.User, core.Device, core.Protocol, ReceiptSubject) bool
	AllowedAction func(context.Context, *core.User, core.Device, core.Protocol, ReceiptSubject, frontend.RowInteractionKind) bool
	Record        func(context.Context, *core.User, core.Device, core.Protocol, ReceiptSubject, frontend.RowInteractionKind) error
	Now           func() time.Time
	TTL           time.Duration
	MaxPerDevice  int
	PolicyLease   func(context.Context) (func(), error)
	// Generation, when set, is stored on the authority row and rechecked on
	// report. Nil stores 0 and does not recheck, which is the mixed-version
	// behavior for callers that have no generation.
	Generation func(context.Context, *core.User, core.Device, core.Protocol) (int64, error)
	// contains filtered or unexported fields
}

type ReceiptSubject struct {
	Kind, ID   string
	Purpose    core.RowPurpose
	Rank       int
	Impression *core.NeutralImpression
}

type Receipts struct {
	// contains filtered or unexported fields
}

type Recent struct {
	Visibility   Visibility
	Unrestricted func(*core.User) bool
}

type RelatedArtworkDeps struct {
	Authorize func(context.Context, *core.Viewer, core.Device, core.RatingKey) (*core.Viewer, error)
	List      func(context.Context, *core.Viewer, core.Device, core.RatingKey) ([]frontend.Image, bool, error)
}

type RelatedArtworkService struct {
	// contains filtered or unexported fields
}

type RelatedCandidate struct {
	Index int
	Items []core.Title
}

type ResumeCandidates interface {
	Continue(context.Context, *core.User, int) ([]core.Title, error)
}

type RowEntryPolicy struct {
	Visibility Visibility
	Favorite   func(context.Context, *core.User, FavoriteSubject) bool
	Playlist   func(context.Context, *core.User, core.RatingKey) bool
}

type RowInteractionPolicy struct {
	Libraries         []Library
	Visibility        Visibility
	Get               func(context.Context, core.RatingKey) (*core.Title, error)
	AllowEntry        func(context.Context, *core.User, string, string) bool
	CollectionMembers func(context.Context, *core.User, core.RatingKey, []core.NeutralEntryRef) bool
	Impression        func(*core.User, core.NeutralImpression)
	DetailOpen        func(context.Context, *core.User, *core.Title)
}

type RowSelection struct {
	Visibility          Visibility
	PrioritizeAvailable func(context.Context, []core.Title) []core.Title
	SameDayUnavailable  func(context.Context, *core.Title) bool
}

type RowServiceDeps struct {
	Source     RowSource
	Visibility Visibility
	Active     func(context.Context, *core.User) bool
	AllowRow   func(context.Context, *core.User, frontend.Row) bool
	AllowEntry func(context.Context, *core.User, frontend.RowEntry) bool
	Layout     func(context.Context, frontend.RowRequest, []frontend.Row) ([]frontend.Row, error)
	Receipts   *Receipts
	Situation  func(context.Context, frontend.RowRequest) (core.HomeSituation, error)
	// HomeFallback supplies bounded library rows when a neutral Home has no
	// discovery shelves left after policy filtering. Plex does not use it.
	HomeFallback func(context.Context, frontend.RowRequest) ([]frontend.Row, error)
	// RankedSource disables retries when the source ranks policy-filtered candidates once.
	RankedSource bool
}

type RowSource interface {
	Rows(context.Context, frontend.RowRequest) ([]frontend.Row, error)
}

type RowViewCollectionItems func(ctx context.Context, viewer *core.User, collection core.RatingKey, offset, limit int) (RowViewCollectionPage, error)

type RowViewCollectionPage struct {
	Keys  []core.RatingKey
	Total int
}

type RowViewCollectionSource interface {
	Items(context.Context, *core.User, core.RatingKey, int, int) (core.Page, error)
}

type RowViewEntry func(ctx context.Context, ref core.NeutralEntryRef) (frontend.RowEntry, error)

type RowViewGuide func(ctx context.Context) ([]frontend.RowEntry, error)

type RowViewOptions struct {
	DB     *sql.DB
	TTL    time.Duration
	Now    func() time.Time
	Active func(context.Context, int64) (*core.User, error)
	Build  func(context.Context, frontend.RowViewRequest) ([]RowViewSnapshot, error)
	// ValidRow checks current placement, collection and viewer preference scope,
	// including the snapshot revision; it must fail closed on uncertainty.
	ValidRow     func(context.Context, *core.User, core.Device, core.Protocol, RowViewSnapshot) bool
	ResolveEntry func(context.Context, *core.User, core.Device, core.Protocol, core.NeutralEntryRef) (frontend.RowEntry, error)
	// ResolveEntries may batch rehydration; every call must perform fresh policy checks.
	ResolveEntries func(context.Context, *core.User, core.Device, core.Protocol, []core.NeutralEntryRef) ([]frontend.RowEntry, error)
	Receipts       *Receipts
}

type RowViewService struct {
	// contains filtered or unexported fields
}

type RowViewSnapshot struct {
	Row       frontend.Row
	Situation core.HomeSituation
	Placement frontend.Placement
	ViewID    string
	Item      core.RatingKey
	Entries   []core.NeutralEntryRef
	Truncated bool
	Revision  string
}

type RowViewTitleBatch func(ctx context.Context, keys []core.RatingKey) (map[core.RatingKey]core.Title, error)

type RowViewTitleRead func(ctx context.Context, key core.RatingKey) (*core.Title, error)

type RowsService struct {
	// contains filtered or unexported fields
}

type RuntimeRowViews struct {
	DB                  *sql.DB
	CurrentAvailable    func(context.Context, []core.Title) []core.Title
	Protocol            core.Protocol
	Receipts            *Receipts
	Visibility          Visibility
	Libraries           []Library
	Active              func(context.Context, int64) (*core.User, error)
	CachedGet           func(context.Context, core.RatingKey) (*core.Title, error)
	CachedGetMany       func(context.Context, []core.RatingKey) (map[core.RatingKey]core.Title, error)
	CachedVirtualSeason func(context.Context, *core.User, core.RatingKey) (*core.Title, error)
	Collections         core.Collections
	Playlists           core.Playlists
	Live                LiveGuideSource
	Situation           func(frontend.RowRequest) core.HomeSituation
	Snapshot            func(context.Context, frontend.RowRequest, core.HomeSituation) ([]frontend.Row, error)
}

type ScopedCollection struct {
	Collections core.Collections
	Visibility  Visibility
	Now         func() time.Time
	// Unrestricted is a trusted host capability; nil enforces inherited policy.
	Unrestricted func(*core.User) bool
}

type Search struct {
	Visibility Visibility
	Vibe       VibeSearch
	Natural    func(context.Context, *core.User, string, int) ([]core.Title, bool)
	Catalog    func(context.Context, string, []core.MediaType, int) ([]core.Title, error)
	// Unrestricted is a trusted host policy capability. Nil uses the
	// restricted, inherited-policy and availability path.
	Unrestricted func(*core.User) bool
}

type SearchResults struct {
	Collection       *core.Collection
	Items            []core.Title
	CollectionSearch bool
}

type Service struct {
	// contains filtered or unexported fields
}

type ServiceDeps struct {
	// BeginPeopleRead supplies fresh, fenced policy facts for the optional People API.
	BeginPeopleRead     func(context.Context, *core.User) (PeopleRead, error)
	NotInterestedSource func(context.Context, *core.User) ([]frontend.NotInterestedEntry, error)
	ByExternalID        func(context.Context, string, string) (*core.Title, error)
	Active              func(context.Context, int64) (*core.User, error)
	Libraries           []Library
	// LiveLibraries, when set, is read on each surface call so configured
	// names stay current. IDs and media types stay stable. Nil uses Libraries.
	LiveLibraries func() []Library
	Visibility    Visibility
	Get           func(context.Context, *core.User, core.RatingKey) (*core.Title, error)
	// CachedGet applies catalogue visibility without a network refresh.
	CachedGet func(context.Context, core.RatingKey) (*core.Title, error)
	// CachedGetMany reads current cached rows in bounded batches without refresh.
	CachedGetMany func(context.Context, []core.RatingKey) (map[core.RatingKey]core.Title, error)
	// ParentTitles resolves distinct parents using the same semantics as GetTitle.
	ParentTitles func(context.Context, []core.RatingKey) (map[core.RatingKey]core.Title, error)
	// CachedVirtualSeason resolves a viewer's already-computed episode layout.
	CachedVirtualSeason func(context.Context, *core.User, core.RatingKey) (*core.Title, error)
	Children            func(context.Context, *core.User, core.RatingKey) ([]core.Title, error)
	Grandchildren       func(context.Context, *core.User, core.RatingKey) ([]core.Title, error)
	// SeasonEpisodes pages one catalogue season. ok is false when this viewer
	// uses a custom episode group and the caller must use Grandchildren.
	SeasonEpisodes func(context.Context, *core.User, core.RatingKey, int, int, int) (core.Page, bool, error)
	Browse         func(context.Context, core.BrowseQuery) (core.Page, error)
	// PageExclusions are viewer-specific SQL exclusions for an indexed library
	// page: hidden titles, blocked genres, blocked keywords, the policy
	// content-rating cap, and parsed plex.tv share filters. Nil keeps the
	// catalogue scan, which still applies filters the SQL page cannot see.
	PageExclusions func(context.Context, *core.User) LibraryPageExclusions
	// CountBrowsable is the indexed library size. The view list uses it instead
	// of browsing titles.
	CountBrowsable func(context.Context, core.MediaType) (int, error)
	// CreditItems enumerates cached credit-title keys without browsing or hydration.
	CreditItems func(context.Context, core.RatingKey, int) ([]core.RatingKey, error)
	// PeopleIndex lists credited people with a name word starting with every
	// term, most credited first. PersonCredits lists a person's most popular
	// credited titles of the given types. With both, people searches use the
	// name index instead of walking every credited title. Optional.
	PeopleIndex   func(context.Context, []string, int) ([]PersonCandidate, error)
	PersonCredits func(context.Context, int64, []core.MediaType, int) ([]core.RatingKey, error)
	AiredEpisodes func(context.Context, core.RatingKey, int, int) (core.Page, error)
	// StoredEpisodes answers a recursive episode listing from the stored
	// episodes in key order. Optional; without it the listing walks the
	// library.
	StoredEpisodes StoredEpisodeDeps
	AddedTimes     func(context.Context, []core.RatingKey) (map[core.RatingKey]time.Time, error)
	// RecentAir is the indexed date-added window. Nil keeps the catalogue scan.
	RecentAir func(context.Context, core.MediaType, int, int) ([]core.Title, bool, error)
	// CountUnplayedAired counts aired episodes with no play. Nil keeps the episode list.
	CountUnplayedAired func(context.Context, int64, []core.RatingKey, string) (map[core.RatingKey]int, error)
	SimilarSource      func(context.Context, core.RatingKey, int) ([]core.Title, error)
	// Related is the same detail recommender Plex uses. Jellyfin and Emby
	// Similar flatten its policy-filtered rows.
	Related               core.Recommender
	FilterRecommendations func(context.Context, *core.User, []core.Title) ([]core.Title, error)
	Collections           core.Collections
	Playlists             core.Playlists
	// Scheduled lists metadata-only future episodes for one season. Nil means
	// the host has not opted in. Callers must not resolve a release from it.
	Scheduled func(context.Context, core.RatingKey) ([]core.Title, error)
	// Grouped reports shows whose episode order is not the canonical season
	// tree. Future episodes stay off those shows.
	Grouped  func(context.Context, *core.User, []core.RatingKey) (map[core.RatingKey]bool, error)
	State    core.State
	Search   Search
	Rows     *RowsService
	Protocol core.Protocol
	// Favorites manages the stable, per-viewer Favorites playlist mapping.
	Favorites               func(context.Context, *core.User, core.RatingKey, bool) (bool, error)
	IsFavorite              func(context.Context, *core.User, core.RatingKey) (bool, error)
	IsFavoriteMany          func(context.Context, *core.User, []core.RatingKey) (map[core.RatingKey]bool, error)
	IsNotInterestedMany     func(context.Context, *core.User, []core.RatingKey) (map[core.RatingKey]bool, error)
	IsWatchlistedMany       func(context.Context, int64, []core.RatingKey) (map[core.RatingKey]bool, error)
	FavoriteMembership      func(context.Context, *core.User, core.RatingKey) (frontend.Membership, error)
	IsNotInterested         func(context.Context, *core.User, core.RatingKey) (bool, error)
	SetNotInterestedSource  func(context.Context, *core.User, core.RatingKey, bool) error
	IsWatchlisted           func(context.Context, *core.User, core.RatingKey) (bool, error)
	WatchlistMembership     func(context.Context, *core.User, core.RatingKey) (frontend.Membership, error)
	SetWatchlistSource      func(context.Context, *core.User, core.RatingKey, bool) error
	RemoveContinue          func(context.Context, *core.User, core.RatingKey) error
	CanFavoriteEntity       func(context.Context, *core.User, frontend.FavoriteRef) bool
	SetEntityFavoriteSource func(context.Context, *core.User, frontend.FavoriteRef, bool) error
	EntityFavoritesSource   func(context.Context, *core.User, []frontend.FavoriteRef) (map[frontend.FavoriteRef]bool, error)

	// Enrich must use cached or estimated data; it must never resolve releases.
	Enrich func(context.Context, *core.User, core.Device, *core.Title) (frontend.ItemDetail, error)
}

type StoredEpisodeDeps struct {
	// Page returns stored, aired, non-adult episodes after a key, in key
	// order, of the series a browse filter admits.
	Page func(context.Context, core.Filter, core.RatingKey, int) ([]core.Title, error)
	// Count counts Page's whole set.
	Count func(context.Context, core.Filter) (int, error)
	// Unranked reports that no stored episode has a popularity.
	Unranked func(context.Context) (bool, error)
	// Customized reports that the viewer, or the owner's defaults, change
	// some series' episode set (an episode group or hidden specials).
	Customized func(context.Context, *core.User) (bool, error)
}

type TrackPreferenceSource interface {
	Select(context.Context, int64, core.RatingKey, core.MediaInfo, string) (trackprefs.Selection, error)
	GetRules(context.Context, int64) (trackprefs.Rules, error)
}

type TrackPreferences struct {
	Source   TrackPreferenceSource
	GetTitle func(context.Context, core.RatingKey) (*core.Title, error)
}

type TrackSelection struct {
	Audio, Subtitle       int
	AudioSet, SubtitleSet bool
}

type UnsupportedPlexTrackIdentityError struct {
	Reason string
}

type VersionObservationPort interface {
	ObserveBatch(context.Context, core.RatingKey, []string, time.Time) (map[string]time.Time, error)
}

type VersionOffer struct {
	ID          string
	Name        string
	Edition     string
	Media       core.MediaInfo
	AddedAt     time.Time
	Publication *time.Time
	// contains filtered or unexported fields
}

type VibeSearch struct {
	Source     VibeSource
	Visibility Visibility
	// Unrestricted is a trusted host policy capability; nil fails closed.
	Unrestricted func(*core.User) bool
}

type VibeSource interface {
	VibeCollection(context.Context, *core.User, string) (*core.Collection, []core.Title, bool, error)
}

type VirtualPathCatalog struct {
	Views        func(context.Context, *core.Viewer) ([]VirtualPathView, error)
	LibraryItems func(context.Context, *core.Viewer, core.Device, string, int, int) (VirtualPathPage, error)
	Children     func(context.Context, *core.Viewer, core.Device, core.RatingKey, int, int) (VirtualPathPage, error)
}

type VirtualPathPage struct {
	Items []core.Title
	Total int
}

type VirtualPathView struct {
	ID   string
	Type core.MediaType
}

type Visibility struct {
	Policy          AccessPolicy
	SectionFor      func(core.MediaType) (int, bool)
	GetTitle        func(context.Context, core.RatingKey) (*core.Title, error)
	FilterAvailable func(context.Context, []core.Title) []core.Title
	Sessions        func() []*core.PlaySession
}