feat(lidarr): typed HTTP client for v1 API (lookup, add, profiles, ping)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-29 15:25:10 -04:00
parent a5bb79f2a8
commit a43fa09a04
9 changed files with 1036 additions and 0 deletions
@@ -0,0 +1,361 @@
+package lidarr
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+)
+
+// Client wraps Lidarr's v1 HTTP API. BaseURL is the Lidarr instance
+// (e.g. http://lidarr.lan:8686), APIKey comes from Lidarr's settings.
+type Client struct {
+	BaseURL string
+	APIKey  string
+	HTTP    *http.Client
+}
+
+// get executes an authenticated GET request and maps HTTP status codes to
+// typed errors. The caller is responsible for closing the returned body.
+func (c *Client) get(ctx context.Context, path string, q url.Values) (*http.Response, error) {
+	u, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrUnreachable, err)
+	}
+	u.Path = u.Path + path
+	if q != nil {
+		u.RawQuery = q.Encode()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("X-Api-Key", c.APIKey)
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrUnreachable, err)
+	}
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		_ = resp.Body.Close()
+		return nil, ErrAuthFailed
+	}
+	if resp.StatusCode >= 500 {
+		_ = resp.Body.Close()
+		return nil, ErrServerError
+	}
+	if resp.StatusCode >= 400 {
+		_ = resp.Body.Close()
+		return nil, ErrLookupFailed
+	}
+	return resp, nil
+}
+
+// post is the shared POST helper. body must be marshaled JSON. It maps HTTP
+// status codes to typed errors; the caller is responsible for closing the
+// returned body.
+func (c *Client) post(ctx context.Context, path string, body []byte) (*http.Response, error) {
+	u, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrUnreachable, err)
+	}
+	u.Path = u.Path + path
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u.String(), bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("X-Api-Key", c.APIKey)
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrUnreachable, err)
+	}
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		_ = resp.Body.Close()
+		return nil, ErrAuthFailed
+	}
+	if resp.StatusCode >= 500 {
+		_ = resp.Body.Close()
+		return nil, ErrServerError
+	}
+	if resp.StatusCode >= 400 {
+		_ = resp.Body.Close()
+		return nil, ErrLookupFailed
+	}
+	return resp, nil
+}
+
+// LookupArtist hits GET /api/v1/artist/lookup?term=. Returns normalized
+// LookupResults; Secondary is "{first genre} · {albumCount} albums" with
+// missing parts skipped.
+func (c *Client) LookupArtist(ctx context.Context, term string) ([]LookupResult, error) {
+	resp, err := c.get(ctx, "/api/v1/artist/lookup", url.Values{"term": {term}})
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw []struct {
+		ForeignArtistID string   `json:"foreignArtistId"`
+		ArtistName      string   `json:"artistName"`
+		Genres          []string `json:"genres"`
+		AlbumCount      int      `json:"albumCount"`
+		Images          []struct {
+			CoverType string `json:"coverType"`
+			RemoteURL string `json:"remoteUrl"`
+			URL       string `json:"url"`
+		} `json:"images"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	out := make([]LookupResult, 0, len(raw))
+	for _, r := range raw {
+		secondary := ""
+		if len(r.Genres) > 0 {
+			secondary = r.Genres[0]
+		}
+		if r.AlbumCount > 0 {
+			if secondary != "" {
+				secondary += " · "
+			}
+			secondary += strconv.Itoa(r.AlbumCount) + " albums"
+		}
+		out = append(out, LookupResult{
+			MBID:      r.ForeignArtistID,
+			Name:      r.ArtistName,
+			Secondary: secondary,
+			ImageURL:  pickPosterImage(r.Images),
+		})
+	}
+	return out, nil
+}
+
+// LookupAlbum hits GET /api/v1/album/lookup?term=. Returns normalized
+// LookupResults; Secondary is "{artistName} · {year} · {trackCount} tracks".
+func (c *Client) LookupAlbum(ctx context.Context, term string) ([]LookupResult, error) {
+	resp, err := c.get(ctx, "/api/v1/album/lookup", url.Values{"term": {term}})
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw []struct {
+		ForeignAlbumID string `json:"foreignAlbumId"`
+		Title          string `json:"title"`
+		ArtistName     string `json:"artistName"`
+		ReleaseDate    string `json:"releaseDate"`
+		TrackCount     int    `json:"trackCount"`
+		Images         []struct {
+			CoverType string `json:"coverType"`
+			RemoteURL string `json:"remoteUrl"`
+			URL       string `json:"url"`
+		} `json:"images"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	out := make([]LookupResult, 0, len(raw))
+	for _, r := range raw {
+		year := ""
+		if len(r.ReleaseDate) >= 4 {
+			year = r.ReleaseDate[:4]
+		}
+		secondary := r.ArtistName
+		if year != "" {
+			secondary += " · " + year
+		}
+		if r.TrackCount > 0 {
+			secondary += " · " + strconv.Itoa(r.TrackCount) + " tracks"
+		}
+		out = append(out, LookupResult{
+			MBID:      r.ForeignAlbumID,
+			Name:      r.Title,
+			Secondary: secondary,
+			ImageURL:  pickPosterImage(r.Images),
+		})
+	}
+	return out, nil
+}
+
+// LookupTrack hits GET /api/v1/track/lookup?term=. Lidarr's track lookup is
+// per-album under the hood. Secondary is "{albumTitle} · {artistName}".
+func (c *Client) LookupTrack(ctx context.Context, term string) ([]LookupResult, error) {
+	resp, err := c.get(ctx, "/api/v1/track/lookup", url.Values{"term": {term}})
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw []struct {
+		ForeignTrackID string `json:"foreignTrackId"`
+		Title          string `json:"title"`
+		AlbumTitle     string `json:"albumTitle"`
+		ArtistName     string `json:"artistName"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	out := make([]LookupResult, 0, len(raw))
+	for _, r := range raw {
+		secondary := r.AlbumTitle
+		if r.ArtistName != "" {
+			if secondary != "" {
+				secondary += " · "
+			}
+			secondary += r.ArtistName
+		}
+		out = append(out, LookupResult{
+			MBID:      r.ForeignTrackID,
+			Name:      r.Title,
+			Secondary: secondary,
+		})
+	}
+	return out, nil
+}
+
+// AddArtist posts to POST /api/v1/artist. MonitorAll=true sends monitor="all";
+// false sends "future". Returns nil on 2xx; typed error otherwise.
+func (c *Client) AddArtist(ctx context.Context, p AddArtistParams) error {
+	monitor := "future"
+	if p.MonitorAll {
+		monitor = "all"
+	}
+	body, _ := json.Marshal(map[string]any{
+		"foreignArtistId":  p.ForeignArtistID,
+		"qualityProfileId": p.QualityProfileID,
+		"rootFolderPath":   p.RootFolderPath,
+		"monitored":        true,
+		"monitor":          monitor,
+		"addOptions":       map[string]any{"searchForMissingAlbums": true},
+	})
+	resp, err := c.post(ctx, "/api/v1/artist", body)
+	if err != nil {
+		return err
+	}
+	_ = resp.Body.Close()
+	return nil
+}
+
+// AddAlbum posts to POST /api/v1/album. Returns nil on 2xx; typed error
+// otherwise.
+func (c *Client) AddAlbum(ctx context.Context, p AddAlbumParams) error {
+	body, _ := json.Marshal(map[string]any{
+		"foreignAlbumId":   p.ForeignAlbumID,
+		"foreignArtistId":  p.ForeignArtistID,
+		"qualityProfileId": p.QualityProfileID,
+		"rootFolderPath":   p.RootFolderPath,
+		"monitored":        true,
+		"addOptions":       map[string]any{"searchForNewAlbum": true},
+	})
+	resp, err := c.post(ctx, "/api/v1/album", body)
+	if err != nil {
+		return err
+	}
+	_ = resp.Body.Close()
+	return nil
+}
+
+// ListQualityProfiles hits GET /api/v1/qualityprofile and returns the full
+// list of quality profiles configured in Lidarr.
+func (c *Client) ListQualityProfiles(ctx context.Context) ([]QualityProfile, error) {
+	resp, err := c.get(ctx, "/api/v1/qualityprofile", nil)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw []struct {
+		ID   int    `json:"id"`
+		Name string `json:"name"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	out := make([]QualityProfile, len(raw))
+	for i, r := range raw {
+		out[i] = QualityProfile{ID: r.ID, Name: r.Name}
+	}
+	return out, nil
+}
+
+// ListRootFolders hits GET /api/v1/rootfolder and returns the list of root
+// folders configured in Lidarr.
+func (c *Client) ListRootFolders(ctx context.Context) ([]RootFolder, error) {
+	resp, err := c.get(ctx, "/api/v1/rootfolder", nil)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw []struct {
+		Path       string `json:"path"`
+		Accessible bool   `json:"accessible"`
+		FreeSpace  int64  `json:"freeSpace"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	out := make([]RootFolder, len(raw))
+	for i, r := range raw {
+		out[i] = RootFolder{Path: r.Path, Accessible: r.Accessible, FreeSpace: r.FreeSpace}
+	}
+	return out, nil
+}
+
+// Ping hits GET /api/v1/system/status to verify connectivity and returns
+// the Lidarr version string.
+func (c *Client) Ping(ctx context.Context) (PingResult, error) {
+	resp, err := c.get(ctx, "/api/v1/system/status", nil)
+	if err != nil {
+		return PingResult{}, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return PingResult{}, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	var raw struct {
+		Version string `json:"version"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return PingResult{}, fmt.Errorf("%w: %v", ErrInvalidPayload, err)
+	}
+	return PingResult{Version: raw.Version}, nil
+}
+
+// pickPosterImage returns the remote URL (preferred) or local URL for the
+// first image with coverType=="poster". Returns "" when none match.
+func pickPosterImage(imgs []struct {
+	CoverType string `json:"coverType"`
+	RemoteURL string `json:"remoteUrl"`
+	URL       string `json:"url"`
+}) string {
+	for _, img := range imgs {
+		if img.CoverType == "poster" {
+			if img.RemoteURL != "" {
+				return img.RemoteURL
+			}
+			return img.URL
+		}
+	}
+	return ""
+}