starr

README

Starr

Another way to say *arr

Go library to interact with APIs in all the Starr apps.

• Lidarr
• Sonarr
• Radarr
• Readarr

This library is slowly updated as new methods are needed or requested. If you have specific needs this library doesn't currently meet, but should or could, please let me know!

This library is currently in use by:

• Unpackerr
• Notifiarr

Usage

Get it:

go get -u golift.io/starr

Use it:

import "golift.io/starr"

Example

package main

import (
	"fmt"

	"golift.io/starr"
	"golift.io/starr/lidarr"
)

func main() {
	// Get a starr.Config that can plug into any Starr app.
	// starr.New(apiKey, appURL string, timeout time.Duration)
	c := starr.New("abc1234ahsuyka123jh12", "http://localhost:8686", 0)
	// Lets make a lidarr server with the default starr Config.
	l := lidarr.New(c)

	// In addition to GetSystemStatus, you have things like:
	// * l.GetAlbum(albumID int)
	// * l.GetQualityDefinition()
	// * l.GetQualityProfiles()
	// * l.GetRootFolders()
	// * l.GetQueue(maxRecords int)
	// * l.GetAlbum(albumUUID string)
	// * l.GetArtist(artistUUID string)
	status, err := l.GetSystemStatus()
	if err != nil {
		panic(err)
	}

	fmt.Println(status)
}

Documentation

Overview

Package starr is a library for interacting with the APIs in Radarr, Lidarr, Sonarr and Readarr. It consists of the main starr package and one sub package for each starr application. In the basic use, you create a starr Config that contains an API key and an App URL. Pass this into one of the other packages (like radarr), and it's used as an interface to make API calls.

You can either call starr.New() to build an http.Client for you, or create a starr.Config that contains one you control. If you pass a starr.Config into a sub package without an http Client, it will be created for you. There are a lot of option to set this code up from simple and easy to more advanced.

The sub package contain methods and data structures for a number of API endpoints. Each app has somewhere between 50 and 100 API endpoints. This library currently covers about 10% of those. You can retrieve things like movies, albums, series and books. You can retrieve server status, authors, artists and items in queues. You can also add new media to each application with this library.

Index

• Constants
• Variables
• type APIer
• type App
  • func (a App) Lower() string
  • func (a App) String() string
• type BaseQuality
• type Config
  • func New(apiKey, appURL string, timeout time.Duration) *Config
  • func (c *Config) Delete(path string, params url.Values) ([]byte, error)
  • func (c *Config) DeleteInto(path string, params url.Values, v interface{}) error
  • func (c *Config) Get(path string, params url.Values) ([]byte, error)
  • func (c *Config) GetInto(path string, params url.Values, v interface{}) error
  • func (c *Config) Post(path string, params url.Values, body []byte) ([]byte, error)
  • func (c *Config) PostInto(path string, params url.Values, body []byte, v interface{}) error
  • func (c *Config) Put(path string, params url.Values, body []byte) ([]byte, error)
  • func (c *Config) PutInto(path string, params url.Values, body []byte, v interface{}) error
• type Duration
  • func (d *Duration) UnmarshalText(data []byte) (err error)
• type Image
• type IsLoaded
• type KeyValue
• type Link
• type Path
• type Quality
• type QualityRevision
• type Ratings
• type StatusMessage
• type Tag
• type Value

Constants

const (
	DefaultTimeout = 10 * time.Second
)

Defaults for New().

Variables

var (
	// ErrInvalidStatusCode is returned when the server (*arr app) returns a bad status code during an API request.
	ErrInvalidStatusCode = fmt.Errorf("invalid status code, <200||>299")
	// ErrNilClient is returned if you attempt a request with a nil http.Client.
	ErrNilClient = fmt.Errorf("http.Client must not be nil")
	// ErrNilInterface is returned by *Into() methods when a nil interface is provided.
	ErrNilInterface = fmt.Errorf("cannot unmarshal data into a nil or empty interface")
)

Errors you may receive from this package.

Types

type APIer

type APIer interface {
	Get(path string, params url.Values) ([]byte, error)
	Post(path string, params url.Values, body []byte) ([]byte, error)
	Put(path string, params url.Values, body []byte) ([]byte, error)
	Delete(path string, params url.Values) ([]byte, error)
	GetInto(path string, params url.Values, v interface{}) error
	PostInto(path string, params url.Values, body []byte, v interface{}) error
	PutInto(path string, params url.Values, body []byte, v interface{}) error
	DeleteInto(path string, params url.Values, v interface{}) error
}

APIer is used by the sub packages to allow mocking the http methods in tests.

type App

type App string

App can be used to satisfy a context value key. It is not used in this library; provided for convenience.

const (
	Emby     App = "Emby"
	Lidarr   App = "Lidarr"
	Plex     App = "Plex"
	Prowlarr App = "Prowlarr"
	Radarr   App = "Radarr"
	Readarr  App = "Readarr"
	Sonarr   App = "Sonarr"
)

These constants are just here for convenience. If you add more here, add them to String() below.

func (App) Lower

func (a App) Lower() string

Lower turns an App name into a lowercase string.

func (App) String

func (a App) String() string

String turns an App name into a string.

type BaseQuality

type BaseQuality struct {
	ID         int64  `json:"id"`
	Name       string `json:"name"`
	Source     string `json:"source,omitempty"`
	Resolution int    `json:"resolution,omitempty"`
	Modifier   string `json:"modifier,omitempty"`
}

BaseQuality is a base quality profile.

type Config

type Config struct {
	APIKey   string       `json:"api_key" toml:"api_key" xml:"api_key" yaml:"api_key"`
	URL      string       `json:"url" toml:"url" xml:"url" yaml:"url"`
	HTTPPass string       `json:"http_pass" toml:"http_pass" xml:"http_pass" yaml:"http_pass"`
	HTTPUser string       `json:"http_user" toml:"http_user" xml:"http_user" yaml:"http_user"`
	Timeout  Duration     `json:"timeout" toml:"timeout" xml:"timeout" yaml:"timeout"`
	ValidSSL bool         `json:"valid_ssl" toml:"valid_ssl" xml:"valid_ssl" yaml:"valid_ssl"`
	Client   *http.Client `json:"-" toml:"-" xml:"-" yaml:"-"`
}

Config is the data needed to poll Radarr or Sonarr or Lidarr or Readarr. At a minimum, provide a URL and API Key. Set ValidSSL to true if the app has a valid SSL certificate. HTTPUser and HTTPPass are used for Basic HTTP auth, if enabled (not common). Timeout and ValidSSL are used to create the http Client by sub packages. You may set those and call New() in the sub packages to create the http.Client pointer, or you can create your own http.Client before calling subpackage.New().

func New

func New(apiKey, appURL string, timeout time.Duration) *Config

New returns a *starr.Config pointer. This pointer is safe to modify further before passing it into one of the arr app New() procedures.

func (*Config) Delete

func (c *Config) Delete(path string, params url.Values) ([]byte, error)

Get makes a DELETE http request and returns the body.

func (*Config) DeleteInto

func (c *Config) DeleteInto(path string, params url.Values, v interface{}) error

DeleteInto performs an HTTP DELETE against an API path and unmarshals the payload into a pointer interface.

func (*Config) Get

func (c *Config) Get(path string, params url.Values) ([]byte, error)

Get makes a GET http request and returns the body.

func (*Config) GetInto

func (c *Config) GetInto(path string, params url.Values, v interface{}) error

GetInto performs an HTTP GET against an API path and unmarshals the payload into the provided pointer interface.

func (*Config) Post

func (c *Config) Post(path string, params url.Values, body []byte) ([]byte, error)

Post makes a POST http request and returns the body.

func (*Config) PostInto

func (c *Config) PostInto(path string, params url.Values, body []byte, v interface{}) error

PostInto performs an HTTP POST against an API path and unmarshals the payload into the provided pointer interface.

func (*Config) Put

func (c *Config) Put(path string, params url.Values, body []byte) ([]byte, error)

Put makes a PUT http request and returns the body.

func (*Config) PutInto

func (c *Config) PutInto(path string, params url.Values, body []byte, v interface{}) error

PutInto performs an HTTP PUT against an API path and unmarshals the payload into the provided pointer interface.

type Duration

type Duration struct{ time.Duration }

Duration is used to Unmarshal text into a time.Duration value.

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(data []byte) (err error)

UnmarshalText parses a duration type from a config file.

type Image

type Image struct {
	CoverType string `json:"coverType"`
	URL       string `json:"url"`
	RemoteURL string `json:"remoteUrl,omitempty"`
	Extension string `json:"extension,omitempty"`
}

Image is used in a few places.

type IsLoaded

type IsLoaded struct {
	IsLoaded bool `json:"isLoaded"`
}

IsLoaded is a generic struct used in a few places.

type KeyValue

type KeyValue struct {
	Key   string `json:"key"`
	Value int    `json:"value"`
}

KeyValue is yet another reusable generic type.

type Link

type Link struct {
	URL  string `json:"url"`
	Name string `json:"name"`
}

Link is used in a few places.

type Path

type Path struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

Path is for unmanaged folder paths.

type Quality

type Quality struct {
	Name     string           `json:"name,omitempty"`
	ID       int              `json:"id,omitempty"`
	Quality  *BaseQuality     `json:"quality,omitempty"`
	Items    []*Quality       `json:"items"`
	Allowed  bool             `json:"allowed"`
	Revision *QualityRevision `json:"revision,omitempty"` // Not sure which app had this....
}

Quality is a download quality profile attached to a movie, book, track or series. It may contain 1 or more profiles. Readarr does not use Name or ID in this struct.

type QualityRevision

type QualityRevision struct {
	Version  int64 `json:"version"`
	Real     int64 `json:"real"`
	IsRepack bool  `json:"isRepack,omitempty"`
}

QualityRevision is probably used in Sonarr.

type Ratings

type Ratings struct {
	Votes      int64   `json:"votes"`
	Value      float64 `json:"value"`
	Popularity float64 `json:"popularity,omitempty"`
}

Ratings belong to a few types.

type StatusMessage

type StatusMessage struct {
	Title    string   `json:"title"`
	Messages []string `json:"messages"`
}

StatusMessage represents the status of the item. All apps use this.

type Tag

type Tag struct {
	ID    int
	Label string
}

Tag may be applied to nearly anything.

type Value

type Value struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

Value is generic ID/Name struct applied to a few places.