Help us shape the future of Go! Take the 2026 Go Developer Survey

arr

package
v1.33.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2026 License: GPL-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultPositiveCacheTTL is the default TTL for positive cache entries (IDs found)
	// Long TTL because external IDs (IMDb, TMDb, TVDb, TVMaze) are immutable
	DefaultPositiveCacheTTL = 30 * 24 * time.Hour // 30 days

	// DefaultNegativeCacheTTL is the default TTL for negative cache entries (no IDs found)
	// Short TTL because content may be added to *arr instances later
	DefaultNegativeCacheTTL = 1 * time.Hour
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AlternateTitle added in v1.19.0 

type AlternateTitle struct {
	Title             string `json:"title"`
	SeasonNumber      *int   `json:"seasonNumber"`
	SceneSeasonNumber *int   `json:"sceneSeasonNumber"`
}

AlternateTitle represents an ARR alternate title. SeasonNumber/SceneSeasonNumber scope the title to a specific season when present; Sonarr uses null or -1 for series-wide titles. Radarr movies never set these (movies have no seasons).

type Client 

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

Client is an HTTP client for communicating with Sonarr/Radarr v3 API

func NewClient 

func NewClient(baseURL, apiKey string, basicUsername, basicPassword *string, instanceType models.ArrInstanceType, timeoutSeconds int) *Client

NewClient creates a new ARR API client

func (*Client) GetSonarrSeasonEpisodes added in v1.19.0 

func (c *Client) GetSonarrSeasonEpisodes(ctx context.Context, seriesID, seasonNumber int) ([]SonarrEpisodeResource, error)

GetSonarrSeasonEpisodes fetches episodes for a specific Sonarr series season.

func (*Client) LookupByTerm added in v1.26.0 

func (c *Client) LookupByTerm(ctx context.Context, term string, year int) (*ExternalIDsLookupResult, error)

LookupByTerm queries the ARR title-search endpoint (Radarr /api/v3/movie/lookup, Sonarr /api/v3/series/lookup) and returns IDs/titles from the best-matching candidate, or nil when no candidate matches term (and year, when known).

func (*Client) ParseSonarrTitle added in v1.19.0 

func (c *Client) ParseSonarrTitle(ctx context.Context, title string) (*SonarrParseResponse, error)

ParseSonarrTitle returns the full Sonarr parse response for TV lookups that need the series ID.

func (*Client) ParseTitle 

func (c *Client) ParseTitle(ctx context.Context, title string) (*models.ExternalIDs, error)

ParseTitle calls the parse endpoint to resolve a title to external IDs For Sonarr: GET /api/v3/parse?title=<title> For Radarr: GET /api/v3/parse?title=<title>

func (*Client) ParseTitleLookupResult added in v1.19.0 

func (c *Client) ParseTitleLookupResult(ctx context.Context, title string) (*ExternalIDsLookupResult, error)

ParseTitleLookupResult calls the parse endpoint to resolve a title to IDs and ARR title aliases.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping tests connectivity to the ARR instance via GET /api/v3/system/status

type ContentType 

type ContentType string

ContentType represents the type of content being searched 

const (
	ContentTypeMovie   ContentType = "movie"
	ContentTypeTV      ContentType = "tv"
	ContentTypeAnime   ContentType = "anime"
	ContentTypeUnknown ContentType = "unknown"
)

type DebugInstanceResult 

type DebugInstanceResult struct {
	InstanceID   int                 `json:"instance_id"`
	InstanceName string              `json:"instance_name"`
	InstanceType string              `json:"instance_type"`
	IDs          *models.ExternalIDs `json:"ids,omitempty"`
	Error        string              `json:"error,omitempty"`
}

DebugInstanceResult contains the result of querying a single ARR instance

type DebugResolveResult 

type DebugResolveResult struct {
	Title              string                  `json:"title"`
	TitleHash          string                  `json:"title_hash"`
	ContentType        ContentType             `json:"content_type"`
	CacheHit           bool                    `json:"cache_hit"`
	CacheEntry         *models.ArrIDCacheEntry `json:"cache_entry,omitempty"`
	InstancesAvailable int                     `json:"instances_available"`
	InstanceResults    []DebugInstanceResult   `json:"instance_results,omitempty"`
	Error              string                  `json:"error,omitempty"`
}

DebugResolveResult contains detailed debug information about an ID resolution

type ExternalIDsLookupResult added in v1.19.0 

type ExternalIDsLookupResult struct {
	IDs        *models.ExternalIDs
	Titles     []string
	EpisodeMap *models.EpisodeMap
}

ExternalIDsLookupResult contains ARR IDs plus ARR-provided titles for the same content, and the episode map when Sonarr named exactly one absolute-numbered episode.

type ExternalIDsResult 

type ExternalIDsResult struct {
	IDs         *models.ExternalIDs `json:"ids,omitempty"`
	Titles      []string            `json:"titles,omitempty"`
	TitlesKnown bool                `json:"-"`
	// EpisodeMap is set when Sonarr named exactly one absolute-numbered episode.
	// EpisodeMapKnown reports that the map was read; a cached row without it refetches.
	EpisodeMap      *models.EpisodeMap `json:"episode_map,omitempty"`
	EpisodeMapKnown bool               `json:"-"`
	FromCache       bool               `json:"from_cache"`
	ArrInstanceID   *int               `json:"arr_instance_id,omitempty"`
	ContentType     ContentType        `json:"content_type"`
	Source          string             `json:"source,omitempty"`
}

ExternalIDsResult contains the result of an ID lookup

type RadarrMovie 

type RadarrMovie struct {
	ID              int              `json:"id"`
	Title           string           `json:"title"`
	Year            int              `json:"year"`
	OriginalTitle   string           `json:"originalTitle"`
	AlternateTitles []AlternateTitle `json:"alternateTitles"`
	TMDbID          int              `json:"tmdbId"`
	IMDbID          string           `json:"imdbId"`
}

RadarrMovie represents a movie in Radarr (contains external IDs)

type RadarrParseResponse 

type RadarrParseResponse struct {
	Title           string                 `json:"title"`
	ParsedMovieInfo *RadarrParsedMovieInfo `json:"parsedMovieInfo"`
	Movie           *RadarrMovie           `json:"movie"`
}

RadarrParseResponse represents the response from Radarr's /api/v3/parse endpoint

func (*RadarrParseResponse) ExtractExternalIDs 

func (r *RadarrParseResponse) ExtractExternalIDs() *models.ExternalIDs

ExtractExternalIDs extracts external IDs from a Radarr parse response

func (*RadarrParseResponse) ExtractLookupResult added in v1.19.0 

func (r *RadarrParseResponse) ExtractLookupResult() *ExternalIDsLookupResult

ExtractLookupResult extracts external IDs and title aliases from a Radarr parse response.

type RadarrParsedMovieInfo 

type RadarrParsedMovieInfo struct {
	MovieTitle   string `json:"movieTitle"`
	Year         int    `json:"year"`
	IMDbID       string `json:"imdbId"`
	TMDbID       int    `json:"tmdbId"`
	Quality      any    `json:"quality"`
	ReleaseGroup string `json:"releaseGroup"`
	ReleaseHash  string `json:"releaseHash"`
}

RadarrParsedMovieInfo contains parsed movie information from Radarr Note: parsedMovieInfo can contain IDs even when movie is nil (extracted from release name)

type SeasonEpisodeTotalResult added in v1.19.0 

type SeasonEpisodeTotalResult struct {
	TotalEpisodes int      `json:"total_episodes"`
	ArrInstanceID *int     `json:"arr_instance_id,omitempty"`
	Titles        []string `json:"titles,omitempty"`
}

SeasonEpisodeTotalResult contains the resolved episode count for a Sonarr season, plus the show's alternate titles usable for that season (series-wide + same-season).

type Service 

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

Service orchestrates ARR ID lookups with caching

func NewService 

func NewService(instanceStore *models.ArrInstanceStore, cacheStore *models.ArrIDCacheStore) *Service

NewService creates a new ARR service

func (*Service) DebugResolve 

func (s *Service) DebugResolve(ctx context.Context, title string, contentType ContentType) (*DebugResolveResult, error)

DebugResolve resolves a title to IDs and returns detailed debug info

func (*Service) LookupExternalIDs 

func (s *Service) LookupExternalIDs(ctx context.Context, title string, contentType ContentType) (*ExternalIDsResult, error)

LookupExternalIDs queries ARR instances for external IDs based on content type. It checks the cache first, then queries ARR instances in priority order.

func (*Service) LookupSeasonEpisodeTotal added in v1.19.0 

func (s *Service) LookupSeasonEpisodeTotal(ctx context.Context, title string, seasonNumber int) (*SeasonEpisodeTotalResult, error)

LookupSeasonEpisodeTotal queries Sonarr instances for the episode count of a specific season, plus the show's alternate titles usable for that season. When the series resolves but the season's episode rows are unavailable (anime is often stored as one absolute-numbered season), it returns a partial result with TotalEpisodes 0 and the titles intact, so callers must check TotalEpisodes before trusting the count.

func (*Service) TestConnection 

func (s *Service) TestConnection(ctx context.Context, baseURL, apiKey string, basicUsername, basicPassword *string, instanceType models.ArrInstanceType) error

TestConnection tests connectivity to an ARR instance.

func (*Service) TestInstance 

func (s *Service) TestInstance(ctx context.Context, instanceID int) error

TestInstance tests connectivity to an existing ARR instance by ID

type SonarrEpisodeResource added in v1.19.0 

type SonarrEpisodeResource struct {
	ID                    int  `json:"id"`
	SeasonNumber          int  `json:"seasonNumber"`
	EpisodeNumber         int  `json:"episodeNumber"`
	AbsoluteEpisodeNumber *int `json:"absoluteEpisodeNumber"`
}

SonarrEpisodeResource represents the subset of Sonarr episode fields needed for season counts and the episode map. Sonarr sends absoluteEpisodeNumber as null for shows without absolute numbering.

type SonarrParseResponse 

type SonarrParseResponse struct {
	Title             string                   `json:"title"`
	ParsedEpisodeInfo *SonarrParsedEpisodeInfo `json:"parsedEpisodeInfo"`
	Series            *SonarrSeries            `json:"series"`
	Episodes          []SonarrEpisodeResource  `json:"episodes"`
}

SonarrParseResponse represents the response from Sonarr's /api/v3/parse endpoint

func (*SonarrParseResponse) ExtractExternalIDs 

func (r *SonarrParseResponse) ExtractExternalIDs() *models.ExternalIDs

ExtractExternalIDs extracts external IDs from a Sonarr parse response

func (*SonarrParseResponse) ExtractLookupResult added in v1.19.0 

func (r *SonarrParseResponse) ExtractLookupResult() *ExternalIDsLookupResult

ExtractLookupResult extracts external IDs, title aliases, and the episode map from a Sonarr parse response.

type SonarrParsedEpisodeInfo 

type SonarrParsedEpisodeInfo struct {
	SeriesTitle       string `json:"seriesTitle"`
	SeasonNumber      int    `json:"seasonNumber"`
	EpisodeNumbers    []int  `json:"episodeNumbers"`
	Quality           any    `json:"quality"`
	ReleaseGroup      string `json:"releaseGroup"`
	ReleaseHash       string `json:"releaseHash"`
	IsDaily           bool   `json:"isDaily"`
	IsAbsoluteNumber  bool   `json:"isAbsoluteNumbering"`
	IsPossibleSpecial bool   `json:"isPossibleSpecialEpisode"`
}

SonarrParsedEpisodeInfo contains parsed episode information from Sonarr

type SonarrSeries 

type SonarrSeries struct {
	ID              int              `json:"id"`
	Title           string           `json:"title"`
	Year            int              `json:"year"`
	AlternateTitles []AlternateTitle `json:"alternateTitles"`
	TVDbID          int              `json:"tvdbId"`
	TVMazeID        int              `json:"tvMazeId"`
	TMDbID          int              `json:"tmdbId"`
	IMDbID          string           `json:"imdbId"`
}

SonarrSeries represents a series in Sonarr (contains external IDs)

type SystemStatusResponse 

type SystemStatusResponse struct {
	AppName string `json:"appName"`
	Version string `json:"version"`
}

SystemStatusResponse represents the response from /api/v3/system/status (both Sonarr and Radarr)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.