metadata

Documentation

Overview

Package metadata provides shared types for interacting with media metadata provider APIs.

Providers are organized by media category:

• video: TMDb, TheTVDB, Fanart.tv, OMDb, TVmaze, OpenSubtitles
• anime: AniList, AniDB, Kitsu, MyAnimeList
• tracking: Trakt, Simkl, Letterboxd, ListenBrainz
• adult: StashBox, TPDB
• music: MusicBrainz, AudioDB, Deezer, Discogs, Last.fm, Spotify
• book: Google Books, Open Library
• game: IGDB, RAWG, Steam

Individual provider packages build on these shared types to offer provider-specific clients.

Shared Types

Rating, ExternalID, Image, Person, and SearchResult are common across most metadata providers and allow consumers to work with normalized data regardless of the source.

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type AuthFunc
• type BaseClient
  • func NewBaseClient(defaultBaseURL, pkgName string, opts ...Option) *BaseClient
  • func (c *BaseClient) BaseURL() string
  • func (c *BaseClient) DoJSON(ctx context.Context, method, path string, payload, dst any) error
  • func (c *BaseClient) DoRaw(ctx context.Context, method, path string, body io.Reader) (data []byte, statusCode int, err error)
  • func (c *BaseClient) DoRawURL(ctx context.Context, method, rawURL string, body io.Reader) (data []byte, statusCode int, err error)
  • func (c *BaseClient) Get(ctx context.Context, path string, dst any) error
  • func (c *BaseClient) HTTPClient() *http.Client
  • func (c *BaseClient) SetAuth(fn AuthFunc)
  • func (c *BaseClient) UserAgent() string
• type ExternalID
• type Image
• type ImageType
• type MediaType
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithTimeout(d time.Duration) Option
  • func WithUserAgent(ua string) Option
• type Person
• type Rating
• type SearchResult

Constants

const (
	// DefaultTimeout is the default HTTP request timeout used by all providers.
	DefaultTimeout = 30 * time.Second
	// DefaultUserAgent is the default User-Agent header for all providers.
	DefaultUserAgent = "goenvoy/0.0.1"
)

Types

type APIError

type APIError struct {
	// StatusCode is the HTTP response status code.
	StatusCode int `json:"-"`
	// RawBody holds the raw response body.
	RawBody string `json:"-"`
	// contains filtered or unexported fields
}

APIError is returned when a metadata provider API responds with a non-2xx HTTP status code.

func (*APIError) Error

func (e *APIError) Error() string

Error implements the error interface.

type AuthFunc

type AuthFunc func(req *http.Request)

AuthFunc is called before each HTTP request to apply provider-specific authentication (e.g. setting headers or query parameters).

type BaseClient

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

BaseClient is a shared low-level HTTP client for metadata providers. Providers embed BaseClient and use its methods to avoid duplicating HTTP plumbing. The AuthFunc hook is called on every request to apply provider-specific authentication.

func NewBaseClient

func NewBaseClient(defaultBaseURL, pkgName string, opts ...Option) *BaseClient

NewBaseClient creates a BaseClient with the given default base URL and package name (used for error prefixes). Apply shared Option values to configure HTTP client, timeout, user agent, or base URL.

func (*BaseClient) BaseURL

func (c *BaseClient) BaseURL() string

BaseURL returns the configured base URL.

func (*BaseClient) DoJSON

func (c *BaseClient) DoJSON(ctx context.Context, method, path string, payload, dst any) error

DoJSON performs an HTTP request with an optional JSON payload. On success (2xx), it decodes the response into dst. On failure, it returns an *APIError.

func (*BaseClient) DoRaw

func (c *BaseClient) DoRaw(ctx context.Context, method, path string, body io.Reader) (data []byte, statusCode int, err error)

DoRaw executes an HTTP request to baseURL+path and returns the raw response body and status code. Auth, User-Agent, and Accept headers are applied automatically. Use this for providers that need custom error handling while still benefiting from shared HTTP plumbing.

func (*BaseClient) DoRawURL

func (c *BaseClient) DoRawURL(ctx context.Context, method, rawURL string, body io.Reader) (data []byte, statusCode int, err error)

DoRawURL is like [DoRaw] but accepts a fully-constructed URL instead of a path relative to baseURL. Use for providers with query-param auth or custom URL schemes.

func (*BaseClient) Get

func (c *BaseClient) Get(ctx context.Context, path string, dst any) error

Get performs a GET request to baseURL+path, checks for a non-2xx status, and decodes the JSON response into dst.

func (*BaseClient) HTTPClient

func (c *BaseClient) HTTPClient() *http.Client

HTTPClient returns the underlying http.Client.

func (*BaseClient) SetAuth

func (c *BaseClient) SetAuth(fn AuthFunc)

SetAuth configures the authentication callback applied to every request.

func (*BaseClient) UserAgent

func (c *BaseClient) UserAgent() string

UserAgent returns the configured User-Agent string.

type ExternalID

type ExternalID struct {
	// Source identifies the provider (e.g. "imdb", "tvdb", "tmdb").
	Source string `json:"source"`
	// ID is the provider-specific identifier.
	ID string `json:"id"`
}

ExternalID links a media item to an identifier on another service.

type Image

type Image struct {
	// URL is the full URL to the image resource.
	URL string `json:"url"`
	// Type classifies the image (poster, backdrop, logo, still).
	Type ImageType `json:"type"`
	// Language is the ISO 639-1 language code, empty if language-neutral.
	Language string `json:"language,omitempty"`
	// Width is the image width in pixels, zero if unknown.
	Width int `json:"width,omitempty"`
	// Height is the image height in pixels, zero if unknown.
	Height int `json:"height,omitempty"`
}

Image represents a media image with its URL and type.

type ImageType

type ImageType string

ImageType classifies what an image depicts.

const (
	// ImageTypePoster is a vertical poster image.
	ImageTypePoster ImageType = "poster"
	// ImageTypeBackdrop is a wide background/banner image.
	ImageTypeBackdrop ImageType = "backdrop"
	// ImageTypeLogo is a transparent logo or clearart.
	ImageTypeLogo ImageType = "logo"
	// ImageTypeStill is a screenshot or episode still.
	ImageTypeStill ImageType = "still"
)

type MediaType

type MediaType string

MediaType identifies the kind of media item.

const (
	// MediaTypeMovie is a film.
	MediaTypeMovie MediaType = "movie"
	// MediaTypeSeries is a TV series or anime show.
	MediaTypeSeries MediaType = "series"
	// MediaTypePerson is a person (actor, director, etc.).
	MediaTypePerson MediaType = "person"
)

type Option

type Option func(*BaseClient)

Option configures a BaseClient.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the provider's default API base URL.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets a custom http.Client.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout overrides the default HTTP request timeout.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header for all requests.

type Person

type Person struct {
	// Name is the person's display name.
	Name string `json:"name"`
	// Role describes the person's role (e.g. character name or crew position).
	Role string `json:"role"`
	// ImageURL is an optional portrait/headshot URL.
	ImageURL string `json:"imageUrl,omitempty"`
	// ExternalIDs links this person to provider-specific identifiers.
	ExternalIDs []ExternalID `json:"externalIds,omitempty"`
}

Person represents a cast or crew member.

type Rating

type Rating struct {
	// Source identifies the provider (e.g. "imdb", "tmdb", "trakt").
	Source string `json:"source"`
	// Value is the rating value, typically 0–10 or 0–100 depending on provider.
	Value float64 `json:"value"`
	// Votes is the number of votes that make up the rating.
	Votes int `json:"votes"`
}

Rating represents a rating from a metadata provider.

type SearchResult

type SearchResult struct {
	// Title is the primary title of the media item.
	Title string `json:"title"`
	// Year is the release or first-air year, zero if unknown.
	Year int `json:"year,omitempty"`
	// Type classifies the result (movie, series, person).
	Type MediaType `json:"type"`
	// ExternalIDs links this result to provider-specific identifiers.
	ExternalIDs []ExternalID `json:"externalIds,omitempty"`
	// PosterURL is an optional poster image URL.
	PosterURL string `json:"posterUrl,omitempty"`
	// Overview is a short synopsis.
	Overview string `json:"overview,omitempty"`
}

SearchResult is a normalised search hit returned by metadata providers.