Mrixs/yandex-music-api-go
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive godoc documentation to all exported symbols

Browse Source 
- Document all exported types, functions, methods, and constants across 52 files
- Add package-level doc comments to client, models, utils, and ynison packages
- Document HTTP method and endpoint path for each API client method
- Document model struct fields and DeJSON/DeList/ToJSON/ToMap methods
- Fix duplicate package doc comment in internal/models/base.go

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
MrixsandClaude Code committed 2026-10-18 08:57:43 +03:00
1 parent 7a68ad86cb
commit 0456ca0665
54 files changed
+1097 -652
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/client/account.go
+10 -8
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -6,7 +7,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetAccountSettings gets account settings (current user's settings from /account/settings)
// GetAccountSettings gets account settings (current user's settings from /account/settings).
func (c *Client) GetAccountSettings(ctx context.Context) (*models.UserSettings, error) {
var result models.UserSettings
if err := c.request.Get(ctx, "/account/settings", nil, &result); err != nil {
@@ -15,7 +16,7 @@ func (c *Client) GetAccountSettings(ctx context.Context) (*models.UserSettings,
return &result, nil
}
// UpdateAccountSettings updates account settings
// UpdateAccountSettings updates account settings (PUT /account/settings).
func (c *Client) UpdateAccountSettings(ctx context.Context, settings *models.AccountSettings) (*models.AccountSettings, error) {
var result models.AccountSettings
if err := c.request.Put(ctx, "/account/settings", settings, &result); err != nil {
@@ -24,7 +25,7 @@ func (c *Client) UpdateAccountSettings(ctx context.Context, settings *models.Acc
return &result, nil
}
// GetSubscription gets user subscription info
// GetSubscription gets user subscription info (GET /account/subscription).
func (c *Client) GetSubscription(ctx context.Context) (*models.Subscription, error) {
var result models.Subscription
if err := c.request.Get(ctx, "/account/subscription", nil, &result); err != nil {
@@ -33,7 +34,7 @@ func (c *Client) GetSubscription(ctx context.Context) (*models.Subscription, err
return &result, nil
}
// GetPlusInfo gets Plus subscription info
// GetPlusInfo gets Plus subscription info (GET /account/plus).
func (c *Client) GetPlusInfo(ctx context.Context) (*models.PlusInfo, error) {
var result models.PlusInfo
if err := c.request.Get(ctx, "/account/plus", nil, &result); err != nil {
@@ -42,7 +43,7 @@ func (c *Client) GetPlusInfo(ctx context.Context) (*models.PlusInfo, error) {
return &result, nil
}
// GetPromoCodeStatus gets promo code status
// GetPromoCodeStatus gets promo code status (GET /promo-code-status).
func (c *Client) GetPromoCodeStatus(ctx context.Context, code string) (*models.PromoCodeStatus, error) {
params := map[string]string{
"code": code,
@@ -54,7 +55,7 @@ func (c *Client) GetPromoCodeStatus(ctx context.Context, code string) (*models.P
return &result, nil
}
// ActivatePromoCode activates a promo code
// ActivatePromoCode activates a promo code (POST /promo-code/activate).
func (c *Client) ActivatePromoCode(ctx context.Context, code string) (*models.PromoCodeStatus, error) {
params := map[string]string{
"code": code,
@@ -66,7 +67,7 @@ func (c *Client) ActivatePromoCode(ctx context.Context, code string) (*models.Pr
return &result, nil
}
// GetUserSettings gets user settings
// GetUserSettings gets user settings for a specific user (GET /user/settings).
func (c *Client) GetUserSettings(ctx context.Context, userID string) (*models.UserSettings, error) {
params := map[string]string{
"user_id": userID,
@@ -78,7 +79,8 @@ func (c *Client) GetUserSettings(ctx context.Context, userID string) (*models.Us
return &result, nil
}
// GetAccountStatus fetches account status
// GetAccountStatus fetches account status (GET /account/status).
// It returns the account status including account info and Plus subscription status.
func (c *Client) GetAccountStatus(ctx context.Context) (*Status, error) {
var result Status
if err := c.request.Get(ctx, "/account/status", nil, &result); err != nil {
internal/client/albums.go
+7 -3
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,8 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// GetAlbums gets albums by IDs
// GetAlbums gets albums by their IDs (GET /tracks?album-ids=...).
// Returns a slice of Album pointers, or nil if no IDs are provided.
func (c *Client) GetAlbums(ctx context.Context, albumIDs []string) ([]*models.Album, error) {
if len(albumIDs) == 0 {
return nil, nil
@@ -30,7 +32,8 @@ func (c *Client) GetAlbums(ctx context.Context, albumIDs []string) ([]*models.Al
return albums, nil
}
// GetAlbum gets a single album by ID
// GetAlbum gets a single album by ID using GetAlbums.
// Returns an error if no album is found with the given ID.
func (c *Client) GetAlbum(ctx context.Context, albumID string) (*models.Album, error) {
albums, err := c.GetAlbums(ctx, []string{albumID})
if err != nil {
@@ -42,7 +45,8 @@ func (c *Client) GetAlbum(ctx context.Context, albumID string) (*models.Album, e
return albums[0], nil
}
// GetAlbumsWithTracks gets albums with tracks expanded
// GetAlbumsWithTracks gets albums with tracks expanded (GET /tracks?with-tracks=true).
// Returns a slice of Album pointers with their tracks populated.
func (c *Client) GetAlbumsWithTracks(ctx context.Context, albumIDs []string) ([]*models.Album, error) {
if len(albumIDs) == 0 {
return nil, nil
internal/client/artists.go
+9 -6
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -8,7 +9,8 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// GetArtists gets artists by IDs
// GetArtists gets artists by their IDs (GET /tracks?artist-ids=...).
// Returns a slice of Artist pointers, or nil if no IDs are provided.
func (c *Client) GetArtists(ctx context.Context, artistIDs []string) ([]*models.Artist, error) {
if len(artistIDs) == 0 {
return nil, nil
@@ -31,7 +33,8 @@ func (c *Client) GetArtists(ctx context.Context, artistIDs []string) ([]*models.
return artists, nil
}
// GetArtist gets a single artist by ID
// GetArtist gets a single artist by ID using GetArtists.
// Returns an error if no artist is found with the given ID.
func (c *Client) GetArtist(ctx context.Context, artistID string) (*models.Artist, error) {
artists, err := c.GetArtists(ctx, []string{artistID})
if err != nil {
@@ -43,8 +46,8 @@ func (c *Client) GetArtist(ctx context.Context, artistID string) (*models.Artist
return artists[0], nil
}
// GetArtistAlbums gets albums by an artist
// GET /artists/{artist_id}/direct-albums
// GetArtistAlbums gets albums by an artist (GET /artists/{artist_id}/direct-albums).
// The page and pageSize parameters control pagination.
func (c *Client) GetArtistAlbums(ctx context.Context, artistID string, page, pageSize int) (*models.ArtistAlbums, error) {
params := map[string]string{
"page": fmt.Sprintf("%d", page),
@@ -59,8 +62,8 @@ func (c *Client) GetArtistAlbums(ctx context.Context, artistID string, page, pag
return &result, nil
}
// GetArtistTracks gets tracks by an artist
// GET /artists/{artist_id}/tracks
// GetArtistTracks gets tracks by an artist (GET /artists/{artist_id}/tracks).
// The page and pageSize parameters control pagination.
func (c *Client) GetArtistTracks(ctx context.Context, artistID string, page, pageSize int) (*models.ArtistTracks, error) {
params := map[string]string{
"page": fmt.Sprintf("%d", page),
internal/client/auth.go
+10 -6
View File
@@ -13,7 +13,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// DeviceCode represents the device authorization response
// DeviceCode represents the device authorization response from the Yandex OAuth device flow.
type DeviceCode struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
@@ -22,7 +22,7 @@ type DeviceCode struct {
Interval int `json:"interval"`
}
// OAuthToken represents an OAuth token response
// OAuthToken represents an OAuth token response from the Yandex OAuth token endpoint.
type OAuthToken struct {
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
@@ -30,7 +30,9 @@ type OAuthToken struct {
ExpiresIn int `json:"expires_in"`
}
// DeviceAuth performs OAuth Device Flow authentication
// DeviceAuth performs OAuth Device Flow authentication.
// It requests a device code, invokes the onCode callback with it, then polls for the token.
// The onCode callback receives the DeviceCode which contains the user_code and verification URL.
func (r *Request) DeviceAuth(ctx context.Context, onCode func(*DeviceCode)) (*OAuthToken, error) {
// Step 1: Request device code
deviceCode, err := r.requestDeviceCode(ctx)
@@ -47,7 +49,7 @@ func (r *Request) DeviceAuth(ctx context.Context, onCode func(*DeviceCode)) (*OA
return r.pollForToken(ctx, deviceCode)
}
// requestDeviceCode requests a device code from Yandex OAuth
// requestDeviceCode requests a device code from the Yandex OAuth device code endpoint.
func (r *Request) requestDeviceCode(ctx context.Context) (*DeviceCode, error) {
// Use Yandex OAuth endpoint for device auth
data := url.Values{}
@@ -85,7 +87,8 @@ func (r *Request) requestDeviceCode(ctx context.Context) (*DeviceCode, error) {
return &deviceCode, nil
}
// pollForToken polls for the OAuth token
// pollForToken polls the Yandex OAuth token endpoint until the user authorizes the device code.
// It returns the OAuthToken once authorization is complete, or an error if the code expires or is denied.
func (r *Request) pollForToken(ctx context.Context, deviceCode *DeviceCode) (*OAuthToken, error) {
interval := deviceCode.Interval
if interval == 0 {
@@ -155,7 +158,8 @@ func (r *Request) pollForToken(ctx context.Context, deviceCode *DeviceCode) (*OA
}
}
// RefreshToken refreshes an access token using a refresh token
// RefreshToken refreshes an access token using the provided refresh token.
// It makes a POST request to the Yandex OAuth token endpoint with grant_type=refresh_token.
func (r *Request) RefreshToken(ctx context.Context, refreshToken string) (*OAuthToken, error) {
data := url.Values{}
data.Set("grant_type", "refresh_token")
internal/client/clips.go
+5 -5
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetClips gets clips
// GetClips gets clips with pagination (GET /clips).
func (c *Client) GetClips(ctx context.Context, page, pageSize int) ([]*models.Clip, error) {
params := map[string]string{
"page": "1",
@@ -33,7 +34,7 @@ func (c *Client) GetClips(ctx context.Context, page, pageSize int) ([]*models.Cl
return clips, nil
}
// GetClipsWillLike gets clips the user might like
// GetClipsWillLike gets clips the user might like (GET /clips/will/like).
func (c *Client) GetClipsWillLike(ctx context.Context) (*models.ClipsWillLike, error) {
var result models.ClipsWillLike
if err := c.request.Get(ctx, "/clips/will/like", nil, &result); err != nil {
@@ -42,8 +43,7 @@ func (c *Client) GetClipsWillLike(ctx context.Context) (*models.ClipsWillLike, e
return &result, nil
}
// GetArtistClips gets clips by an artist
// GET /artists/{artistID}/blocks/artist-clips
// GetArtistClips gets clips by an artist (GET /artists/{artistID}/blocks/artist-clips).
func (c *Client) GetArtistClips(ctx context.Context, artistID string) (*models.ArtistClipData, error) {
var result models.ArtistClipData
if err := c.request.Get(ctx, fmt.Sprintf("/artists/%s/blocks/artist-clips", artistID), nil, &result); err != nil {
@@ -52,7 +52,7 @@ func (c *Client) GetArtistClips(ctx context.Context, artistID string) (*models.A
return &result, nil
}
// GetShots gets shots
// GetShots gets shots with pagination (GET /shots).
func (c *Client) GetShots(ctx context.Context, page, pageSize int) ([]*models.Shot, error) {
params := map[string]string{
"page": "1",
internal/client/concerts.go
+6 -7
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetConcerts gets concerts
// GetConcerts gets concerts with pagination (GET /concerts).
func (c *Client) GetConcerts(ctx context.Context, page, pageSize int) (*models.ConcertFeed, error) {
params := map[string]string{
"page": "1",
@@ -27,7 +28,7 @@ func (c *Client) GetConcerts(ctx context.Context, page, pageSize int) (*models.C
return &result, nil
}
// GetConcertFeed gets concert feed
// GetConcertFeed gets the concert feed (GET /concerts/feed).
func (c *Client) GetConcertFeed(ctx context.Context) (*models.ConcertFeed, error) {
var result models.ConcertFeed
if err := c.request.Get(ctx, "/concerts/feed", nil, &result); err != nil {
@@ -36,8 +37,7 @@ func (c *Client) GetConcertFeed(ctx context.Context) (*models.ConcertFeed, error
return &result, nil
}
// GetConcertInfo gets concert info
// GET /concerts/{concertID}/info
// GetConcertInfo gets concert info by ID (GET /concerts/{concertID}/info).
func (c *Client) GetConcertInfo(ctx context.Context, concertID string) (*models.ConcertInfo, error) {
var result models.ConcertInfo
if err := c.request.Get(ctx, fmt.Sprintf("/concerts/%s/info", concertID), nil, &result); err != nil {
@@ -46,7 +46,7 @@ func (c *Client) GetConcertInfo(ctx context.Context, concertID string) (*models.
return &result, nil
}
// GetConcertLocations gets concert locations
// GetConcertLocations gets concert locations (GET /concerts/locations).
func (c *Client) GetConcertLocations(ctx context.Context) (*models.ConcertLocations, error) {
var result models.ConcertLocations
if err := c.request.Get(ctx, "/concerts/locations", nil, &result); err != nil {
@@ -55,8 +55,7 @@ func (c *Client) GetConcertLocations(ctx context.Context) (*models.ConcertLocati
return &result, nil
}
// GetConcertTabs gets concert tabs
// GET /concerts/tab-config
// GetConcertTabs gets concert tab configuration (GET /concerts/tab-config).
func (c *Client) GetConcertTabs(ctx context.Context) (*models.ConcertTabConfig, error) {
var result models.ConcertTabConfig
if err := c.request.Get(ctx, "/concerts/tab-config", nil, &result); err != nil {
internal/client/feed.go
+9 -9
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetFeed gets the main feed
// GetFeed gets the main feed (GET /feed).
func (c *Client) GetFeed(ctx context.Context) (*models.Feed, error) {
var result models.Feed
if err := c.request.Get(ctx, "/feed", nil, &result); err != nil {
@@ -16,7 +17,7 @@ func (c *Client) GetFeed(ctx context.Context) (*models.Feed, error) {
return &result, nil
}
// GetFeedBlocks gets feed blocks
// GetFeedBlocks gets feed blocks (GET /feed/blocks).
func (c *Client) GetFeedBlocks(ctx context.Context) ([]*models.DayBlock, error) {
var result []models.DayBlock
if err := c.request.Get(ctx, "/feed/blocks", nil, &result); err != nil {
@@ -31,7 +32,7 @@ func (c *Client) GetFeedBlocks(ctx context.Context) ([]*models.DayBlock, error)
return blocks, nil
}
// GetFeedGeneratedPlaylist gets a generated playlist by ID from feed
// GetFeedGeneratedPlaylist gets a generated playlist by ID from the feed (GET /feed/generated-playlist).
func (c *Client) GetFeedGeneratedPlaylist(ctx context.Context, playlistID string) (*models.GeneratedPlaylist, error) {
params := map[string]string{
"playlist_id": playlistID,
@@ -45,7 +46,7 @@ func (c *Client) GetFeedGeneratedPlaylist(ctx context.Context, playlistID string
return &result, nil
}
// GetFeedDay gets a specific day from the feed
// GetFeedDay gets a specific day from the feed by date (GET /feed/day).
func (c *Client) GetFeedDay(ctx context.Context, date string) (*models.Day, error) {
params := map[string]string{
"date": date,
@@ -58,7 +59,7 @@ func (c *Client) GetFeedDay(ctx context.Context, date string) (*models.Day, erro
return &result, nil
}
// GetGeneratedPlaylists gets generated playlists
// GetGeneratedPlaylists gets generated playlists (GET /generated-playlists).
func (c *Client) GetGeneratedPlaylists(ctx context.Context) ([]*models.GeneratedPlaylist, error) {
var result []models.GeneratedPlaylist
if err := c.request.Get(ctx, "/generated-playlists", nil, &result); err != nil {
@@ -73,8 +74,7 @@ func (c *Client) GetGeneratedPlaylists(ctx context.Context) ([]*models.Generated
return playlists, nil
}
// GetLanding gets a landing page
// GET /landing3/{landingID}
// GetLanding gets a landing page by ID (GET /landing3/{landingID}).
func (c *Client) GetLanding(ctx context.Context, landingID string) (*models.Landing, error) {
params := map[string]string{
"landing_id": landingID,
@@ -87,7 +87,7 @@ func (c *Client) GetLanding(ctx context.Context, landingID string) (*models.Land
return &result, nil
}
// GetLandingList gets a list of landings
// GetLandingList gets a list of landings (GET /landing3/list).
func (c *Client) GetLandingList(ctx context.Context) (*models.LandingList, error) {
var result models.LandingList
if err := c.request.Get(ctx, "/landing3/list", nil, &result); err != nil {
@@ -96,7 +96,7 @@ func (c *Client) GetLandingList(ctx context.Context) (*models.LandingList, error
return &result, nil
}
// GetLandingBlocks gets landing blocks by block IDs
// GetLandingBlocks gets landing blocks by block IDs (GET /landing3/blocks).
func (c *Client) GetLandingBlocks(ctx context.Context, blockIDs []string) ([]*models.LandingBlock, error) {
params := map[string]string{
"blocks": joinStrings(blockIDs, ","),
internal/client/history.go
+4 -3
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetMusicHistory gets music history
// GetMusicHistory gets the user's music history (GET /music-history).
func (c *Client) GetMusicHistory(ctx context.Context) (*models.MusicHistory, error) {
var result models.MusicHistory
if err := c.request.Get(ctx, "/music-history", nil, &result); err != nil {
@@ -16,7 +17,7 @@ func (c *Client) GetMusicHistory(ctx context.Context) (*models.MusicHistory, err
return &result, nil
}
// GetMusicHistoryTabs gets music history tabs
// GetMusicHistoryTabs gets music history tabs (GET /music-history/tabs).
func (c *Client) GetMusicHistoryTabs(ctx context.Context) ([]*models.MusicHistoryTab, error) {
var result []models.MusicHistoryTab
if err := c.request.Get(ctx, "/music-history/tabs", nil, &result); err != nil {
@@ -31,7 +32,7 @@ func (c *Client) GetMusicHistoryTabs(ctx context.Context) ([]*models.MusicHistor
return tabs, nil
}
// GetMusicHistoryItems gets music history items
// GetMusicHistoryItems gets music history items for a tab (GET /music-history/items).
func (c *Client) GetMusicHistoryItems(ctx context.Context, tabID string, page, pageSize int) (*models.MusicHistoryItems, error) {
params := map[string]string{}
if tabID != "" {
internal/client/labels.go
+5 -7
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetLabels gets all labels
// GetLabels gets all labels (GET /labels).
func (c *Client) GetLabels(ctx context.Context) ([]*models.Label, error) {
var result []models.Label
if err := c.request.Get(ctx, "/labels", nil, &result); err != nil {
@@ -22,8 +23,7 @@ func (c *Client) GetLabels(ctx context.Context) ([]*models.Label, error) {
return labels, nil
}
// GetLabel gets a label by ID
// GET /labels/{labelID}
// GetLabel gets a label by ID (GET /labels/{labelID}).
func (c *Client) GetLabel(ctx context.Context, labelID string) (*models.Label, error) {
var result models.Label
if err := c.request.Get(ctx, fmt.Sprintf("/labels/%s", labelID), nil, &result); err != nil {
@@ -33,8 +33,7 @@ func (c *Client) GetLabel(ctx context.Context, labelID string) (*models.Label, e
return &result, nil
}
// GetLabelAlbums gets albums for a label
// GET /labels/{labelID}/albums
// GetLabelAlbums gets albums for a label (GET /labels/{labelID}/albums).
func (c *Client) GetLabelAlbums(ctx context.Context, labelID string, page, pageSize int) (*models.LabelAlbums, error) {
params := map[string]string{}
if page > 0 {
@@ -51,8 +50,7 @@ func (c *Client) GetLabelAlbums(ctx context.Context, labelID string, page, pageS
return &result, nil
}
// GetLabelArtists gets artists for a label
// GET /labels/{labelID}/artists
// GetLabelArtists gets artists for a label (GET /labels/{labelID}/artists).
func (c *Client) GetLabelArtists(ctx context.Context, labelID string, page, pageSize int) (*models.LabelArtists, error) {
params := map[string]string{}
if page > 0 {
internal/client/likes.go
+13 -24
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,8 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// LikeTrack likes a track
// POST /users/me/likes/tracks/add-multiple
// LikeTrack likes a track (POST /users/me/likes/tracks/add-multiple).
func (c *Client) LikeTrack(ctx context.Context, trackID string) error {
params := map[string]string{
"track-ids": trackID,
@@ -17,8 +17,7 @@ func (c *Client) LikeTrack(ctx context.Context, trackID string) error {
return c.request.Post(ctx, "/users/me/likes/tracks/add-multiple", params, &result)
}
// UnlikeTrack unlikes a track
// POST /users/me/likes/tracks/remove
// UnlikeTrack unlikes a track (POST /users/me/likes/tracks/remove).
func (c *Client) UnlikeTrack(ctx context.Context, trackID string) error {
params := map[string]string{
"track-ids": trackID,
@@ -27,8 +26,7 @@ func (c *Client) UnlikeTrack(ctx context.Context, trackID string) error {
return c.request.Post(ctx, "/users/me/likes/tracks/remove", params, &result)
}
// LikeAlbum likes an album
// POST /users/me/likes/albums/add-multiple
// LikeAlbum likes an album (POST /users/me/likes/albums/add-multiple).
func (c *Client) LikeAlbum(ctx context.Context, albumID string) error {
params := map[string]string{
"album-ids": albumID,
@@ -37,8 +35,7 @@ func (c *Client) LikeAlbum(ctx context.Context, albumID string) error {
return c.request.Post(ctx, "/users/me/likes/albums/add-multiple", params, &result)
}
// UnlikeAlbum unlikes an album
// POST /users/me/likes/albums/remove
// UnlikeAlbum unlikes an album (POST /users/me/likes/albums/remove).
func (c *Client) UnlikeAlbum(ctx context.Context, albumID string) error {
params := map[string]string{
"album-ids": albumID,
@@ -47,8 +44,7 @@ func (c *Client) UnlikeAlbum(ctx context.Context, albumID string) error {
return c.request.Post(ctx, "/users/me/likes/albums/remove", params, &result)
}
// LikeArtist likes an artist
// POST /users/me/likes/artists/add-multiple
// LikeArtist likes an artist (POST /users/me/likes/artists/add-multiple).
func (c *Client) LikeArtist(ctx context.Context, artistID string) error {
params := map[string]string{
"artist-ids": artistID,
@@ -57,8 +53,7 @@ func (c *Client) LikeArtist(ctx context.Context, artistID string) error {
return c.request.Post(ctx, "/users/me/likes/artists/add-multiple", params, &result)
}
// UnlikeArtist unlikes an artist
// POST /users/me/likes/artists/remove
// UnlikeArtist unlikes an artist (POST /users/me/likes/artists/remove).
func (c *Client) UnlikeArtist(ctx context.Context, artistID string) error {
params := map[string]string{
"artist-ids": artistID,
@@ -67,8 +62,7 @@ func (c *Client) UnlikeArtist(ctx context.Context, artistID string) error {
return c.request.Post(ctx, "/users/me/likes/artists/remove", params, &result)
}
// LikePlaylist likes a playlist
// POST /users/me/likes/playlists/add-multiple
// LikePlaylist likes a playlist (POST /users/me/likes/playlists/add-multiple).
func (c *Client) LikePlaylist(ctx context.Context, kind int) error {
params := map[string]string{
"playlist-ids": fmt.Sprintf("%d", kind),
@@ -77,8 +71,7 @@ func (c *Client) LikePlaylist(ctx context.Context, kind int) error {
return c.request.Post(ctx, "/users/me/likes/playlists/add-multiple", params, &result)
}
// UnlikePlaylist unlikes a playlist
// POST /users/me/likes/playlists/remove
// UnlikePlaylist unlikes a playlist (POST /users/me/likes/playlists/remove).
func (c *Client) UnlikePlaylist(ctx context.Context, kind int) error {
params := map[string]string{
"playlist-ids": fmt.Sprintf("%d", kind),
@@ -87,8 +80,7 @@ func (c *Client) UnlikePlaylist(ctx context.Context, kind int) error {
return c.request.Post(ctx, "/users/me/likes/playlists/remove", params, &result)
}
// GetLikedTracks gets user's liked tracks
// GET /users/me/likes/tracks
// GetLikedTracks gets the user's liked tracks (GET /users/me/likes/tracks).
func (c *Client) GetLikedTracks(ctx context.Context) ([]*models.Track, error) {
var result []models.Track
if err := c.request.Get(ctx, "/users/me/likes/tracks", nil, &result); err != nil {
@@ -103,8 +95,7 @@ func (c *Client) GetLikedTracks(ctx context.Context) ([]*models.Track, error) {
return tracks, nil
}
// GetLikedAlbums gets user's liked albums
// GET /users/me/likes/albums
// GetLikedAlbums gets the user's liked albums (GET /users/me/likes/albums).
func (c *Client) GetLikedAlbums(ctx context.Context) ([]*models.Album, error) {
var result []models.Album
if err := c.request.Get(ctx, "/users/me/likes/albums", nil, &result); err != nil {
@@ -119,8 +110,7 @@ func (c *Client) GetLikedAlbums(ctx context.Context) ([]*models.Album, error) {
return albums, nil
}
// GetLikedArtists gets user's liked artists
// GET /users/me/likes/artists
// GetLikedArtists gets the user's liked artists (GET /users/me/likes/artists).
func (c *Client) GetLikedArtists(ctx context.Context) ([]*models.Artist, error) {
var result []models.Artist
if err := c.request.Get(ctx, "/users/me/likes/artists", nil, &result); err != nil {
@@ -135,8 +125,7 @@ func (c *Client) GetLikedArtists(ctx context.Context) ([]*models.Artist, error)
return artists, nil
}
// GetLikedPlaylists gets user's liked playlists
// GET /users/me/likes/playlists
// GetLikedPlaylists gets the user's liked playlists (GET /users/me/likes/playlists).
func (c *Client) GetLikedPlaylists(ctx context.Context) ([]*models.Playlist, error) {
var result []models.Playlist
if err := c.request.Get(ctx, "/users/me/likes/playlists", nil, &result); err != nil {
internal/client/metatags.go
+11 -10
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetMetatags gets all metatags
// GetMetatags gets all metatags (GET /metatags).
func (c *Client) GetMetatags(ctx context.Context) ([]*models.Metatag, error) {
var result []models.Metatag
if err := c.request.Get(ctx, "/metatags", nil, &result); err != nil {
@@ -22,7 +23,7 @@ func (c *Client) GetMetatags(ctx context.Context) ([]*models.Metatag, error) {
return metatags, nil
}
// GetMetatagTree gets metatag tree
// GetMetatagTree gets the metatag tree (GET /metatags/tree).
func (c *Client) GetMetatagTree(ctx context.Context) (*models.MetatagTree, error) {
var result models.MetatagTree
if err := c.request.Get(ctx, "/metatags/tree", nil, &result); err != nil {
@@ -31,7 +32,7 @@ func (c *Client) GetMetatagTree(ctx context.Context) (*models.MetatagTree, error
return &result, nil
}
// GetMetatagArtists gets artists for a metatag
// GetMetatagArtists gets artists for a metatag (GET /metatags/artists).
func (c *Client) GetMetatagArtists(ctx context.Context, metatagID string, page, pageSize int) (*models.MetatagArtists, error) {
params := map[string]string{
"metatag_id": metatagID,
@@ -50,7 +51,7 @@ func (c *Client) GetMetatagArtists(ctx context.Context, metatagID string, page,
return &result, nil
}
// GetMetatagAlbums gets albums for a metatag
// GetMetatagAlbums gets albums for a metatag (GET /metatags/albums).
func (c *Client) GetMetatagAlbums(ctx context.Context, metatagID string, page, pageSize int) (*models.MetatagAlbums, error) {
params := map[string]string{
"metatag_id": metatagID,
@@ -69,7 +70,7 @@ func (c *Client) GetMetatagAlbums(ctx context.Context, metatagID string, page, p
return &result, nil
}
// GetMetatagPlaylists gets playlists for a metatag
// GetMetatagPlaylists gets playlists for a metatag (GET /metatags/playlists).
func (c *Client) GetMetatagPlaylists(ctx context.Context, metatagID string, page, pageSize int) (*models.MetatagPlaylists, error) {
params := map[string]string{
"metatag_id": metatagID,
@@ -88,7 +89,7 @@ func (c *Client) GetMetatagPlaylists(ctx context.Context, metatagID string, page
return &result, nil
}
// GetGenres gets all genres
// GetGenres gets all genres (GET /genres).
func (c *Client) GetGenres(ctx context.Context) ([]*models.Genre, error) {
var result []models.Genre
if err := c.request.Get(ctx, "/genres", nil, &result); err != nil {
@@ -103,7 +104,7 @@ func (c *Client) GetGenres(ctx context.Context) ([]*models.Genre, error) {
return genres, nil
}
// GetCharts gets charts
// GetCharts gets all charts (GET /charts).
func (c *Client) GetCharts(ctx context.Context) ([]*models.Chart, error) {
var result []models.Chart
if err := c.request.Get(ctx, "/charts", nil, &result); err != nil {
@@ -118,7 +119,7 @@ func (c *Client) GetCharts(ctx context.Context) ([]*models.Chart, error) {
return charts, nil
}
// GetChartInfo gets chart info
// GetChartInfo gets chart info for a chart ID (GET /charts/info).
func (c *Client) GetChartInfo(ctx context.Context, chartID string) (*models.ChartInfo, error) {
params := map[string]string{
"chart_id": chartID,
@@ -131,7 +132,7 @@ func (c *Client) GetChartInfo(ctx context.Context, chartID string) (*models.Char
return &result, nil
}
// GetChartItems gets chart items
// GetChartItems gets chart items for a chart ID (GET /charts/items).
func (c *Client) GetChartItems(ctx context.Context, chartID string, page, pageSize int) (*models.ChartItems, error) {
params := map[string]string{
"chart_id": chartID,
@@ -150,7 +151,7 @@ func (c *Client) GetChartItems(ctx context.Context, chartID string, page, pageSi
return &result, nil
}
// GetChartMenu gets chart menu
// GetChartMenu gets chart menu for a chart ID (GET /charts/menu).
func (c *Client) GetChartMenu(ctx context.Context, chartID string) (*models.ChartInfoMenu, error) {
params := map[string]string{
"chart_id": chartID,
internal/client/pins.go
+5 -4
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -6,7 +7,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetPins gets user's pins
// GetPins gets user's pins (GET /pins).
func (c *Client) GetPins(ctx context.Context) (*models.PinsList, error) {
var result models.PinsList
if err := c.request.Get(ctx, "/pins", nil, &result); err != nil {
@@ -15,7 +16,7 @@ func (c *Client) GetPins(ctx context.Context) (*models.PinsList, error) {
return &result, nil
}
// AddPin adds a pin
// AddPin adds a pin (POST /pins).
func (c *Client) AddPin(ctx context.Context, pinType, entityID string) (*models.Pin, error) {
params := map[string]string{
"type": pinType,
@@ -29,7 +30,7 @@ func (c *Client) AddPin(ctx context.Context, pinType, entityID string) (*models.
return &result, nil
}
// RemovePin removes a pin
// RemovePin removes a pin by ID (DELETE /pins).
func (c *Client) RemovePin(ctx context.Context, pinID string) error {
params := map[string]string{
"pin_id": pinID,
@@ -38,7 +39,7 @@ func (c *Client) RemovePin(ctx context.Context, pinID string) error {
return c.request.Delete(ctx, "/pins", params, &result)
}
// GetPresaves gets user's presaves
// GetPresaves gets user's presaves (GET /presaves).
func (c *Client) GetPresaves(ctx context.Context) (*models.Presaves, error) {
var result models.Presaves
if err := c.request.Get(ctx, "/presaves", nil, &result); err != nil {
internal/client/playlists.go
+18 -11
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -8,7 +9,8 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// GetPlaylists gets playlists by IDs (kinds)
// GetPlaylists gets playlists by their kind IDs (GET /playlists).
// Returns a slice of Playlist pointers, or nil if no kinds are provided.
func (c *Client) GetPlaylists(ctx context.Context, kinds []int) ([]*models.Playlist, error) {
if len(kinds) == 0 {
return nil, nil
@@ -40,7 +42,8 @@ func (c *Client) GetPlaylists(ctx context.Context, kinds []int) ([]*models.Playl
return playlists, nil
}
// GetPlaylist gets a single playlist by kind
// GetPlaylist gets a single playlist by kind using GetPlaylists.
// Returns an error if no playlist is found with the given kind.
func (c *Client) GetPlaylist(ctx context.Context, kind int) (*models.Playlist, error) {
playlists, err := c.GetPlaylists(ctx, []int{kind})
if err != nil {
@@ -52,8 +55,7 @@ func (c *Client) GetPlaylist(ctx context.Context, kind int) (*models.Playlist, e
return playlists[0], nil
}
// GetUserPlaylists gets playlists for a user
// GET /users/{userID}/playlists
// GetUserPlaylists gets playlists for a user (GET /users/{userID}/playlists).
func (c *Client) GetUserPlaylists(ctx context.Context, userID string) ([]*models.Playlist, error) {
var result []models.Playlist
if err := c.request.Get(ctx, fmt.Sprintf("/users/%s/playlists", userID), nil, &result); err != nil {
@@ -68,7 +70,8 @@ func (c *Client) GetUserPlaylists(ctx context.Context, userID string) ([]*models
return playlists, nil
}
// CreatePlaylist creates a new playlist
// CreatePlaylist creates a new playlist (POST /users/me/playlists).
// The visibility parameter should be "public" or "private".
func (c *Client) CreatePlaylist(ctx context.Context, title string, visibility string) (*models.Playlist, error) {
params := map[string]string{
"title": title,
@@ -83,7 +86,8 @@ func (c *Client) CreatePlaylist(ctx context.Context, title string, visibility st
return &result, nil
}
// EditPlaylist edits an existing playlist
// EditPlaylist edits an existing playlist (PUT /users/me/playlists).
// Only non-empty parameters are updated.
func (c *Client) EditPlaylist(ctx context.Context, kind int, title, description, visibility string) (*models.Playlist, error) {
params := map[string]string{
"kind": fmt.Sprintf("%d", kind),
@@ -106,7 +110,7 @@ func (c *Client) EditPlaylist(ctx context.Context, kind int, title, description,
return &result, nil
}
// DeletePlaylist deletes a playlist
// DeletePlaylist deletes a playlist (DELETE /users/me/playlists).
func (c *Client) DeletePlaylist(ctx context.Context, kind int) error {
params := map[string]string{
"kind": fmt.Sprintf("%d", kind),
@@ -115,7 +119,8 @@ func (c *Client) DeletePlaylist(ctx context.Context, kind int) error {
return c.request.Delete(ctx, "/users/me/playlists", params, &result)
}
// AddTracksToPlaylist adds tracks to a playlist
// AddTracksToPlaylist adds tracks to a playlist (POST /users/me/playlists/tracks).
// The revision parameter is the current playlist revision for optimistic concurrency.
func (c *Client) AddTracksToPlaylist(ctx context.Context, kind int, trackIDs []string, revision int) (*models.Playlist, error) {
if len(trackIDs) == 0 {
return nil, utils.NewYandexMusicError("no tracks provided", utils.ErrBadRequest)
@@ -143,7 +148,8 @@ func (c *Client) AddTracksToPlaylist(ctx context.Context, kind int, trackIDs []s
return &result, nil
}
// RemoveTracksFromPlaylist removes tracks from a playlist
// RemoveTracksFromPlaylist removes tracks from a playlist (DELETE /users/me/playlists/tracks).
// The revision parameter is the current playlist revision for optimistic concurrency.
func (c *Client) RemoveTracksFromPlaylist(ctx context.Context, kind int, trackIDs []string, revision int) (*models.Playlist, error) {
if len(trackIDs) == 0 {
return nil, utils.NewYandexMusicError("no tracks provided", utils.ErrBadRequest)
@@ -171,7 +177,8 @@ func (c *Client) RemoveTracksFromPlaylist(ctx context.Context, kind int, trackID
return &result, nil
}
// ReorderPlaylistTracks reorders tracks in a playlist
// ReorderPlaylistTracks reorders tracks in a playlist (PUT /users/me/playlists/tracks/reorder).
// The from and to parameters specify the position range to move.
func (c *Client) ReorderPlaylistTracks(ctx context.Context, kind int, from, to, revision int) (*models.Playlist, error) {
params := map[string]string{
"kind": fmt.Sprintf("%d", kind),
@@ -188,7 +195,7 @@ func (c *Client) ReorderPlaylistTracks(ctx context.Context, kind int, from, to,
return &result, nil
}
// GetPlaylistRecommendations gets playlist recommendations
// GetPlaylistRecommendations gets playlist recommendations based on a playlist kind (GET /playlists/recommendations).
func (c *Client) GetPlaylistRecommendations(ctx context.Context, kind int) ([]*models.Playlist, error) {
params := map[string]string{
"kind": fmt.Sprintf("%d", kind),
internal/client/queue.go
+20 -30
View File
@@ -17,7 +17,8 @@ func (c *Client) GetQueue(ctx context.Context) (*models.Queue, error) {
return &result, nil
}
// CreateQueue creates a new queue
// CreateQueue creates a new playback queue (POST /queues).
// The queueType parameter specifies the type of queue (e.g., "radio", "album", "playlist").
func (c *Client) CreateQueue(ctx context.Context, trackID string, queueType string) (*models.Queue, error) {
params := map[string]string{
"track_id": trackID,
@@ -32,8 +33,7 @@ func (c *Client) CreateQueue(ctx context.Context, trackID string, queueType stri
return &result, nil
}
// GetQueueItem gets a queue item
// GET /queues/{queue_id}
// GetQueueItem gets a queue item by queue ID (GET /queues/{queue_id}).
func (c *Client) GetQueueItem(ctx context.Context, queueID string) (*models.QueueItem, error) {
var result models.QueueItem
if err := c.request.Get(ctx, fmt.Sprintf("/queues/%s", queueID), nil, &result); err != nil {
@@ -43,8 +43,7 @@ func (c *Client) GetQueueItem(ctx context.Context, queueID string) (*models.Queu
return &result, nil
}
// AddToQueue adds a track to the queue
// POST /queues/{queue_id}/add
// AddToQueue adds a track to the queue at the given position (POST /queues/{queue_id}/add).
func (c *Client) AddToQueue(ctx context.Context, queueID, trackID string, position int) (*models.Queue, error) {
params := map[string]string{
"track_id": trackID,
@@ -59,8 +58,7 @@ func (c *Client) AddToQueue(ctx context.Context, queueID, trackID string, positi
return &result, nil
}
// RemoveFromQueue removes a track from the queue
// DELETE /queues/{queue_id}/remove
// RemoveFromQueue removes a track from the queue (DELETE /queues/{queue_id}/remove).
func (c *Client) RemoveFromQueue(ctx context.Context, queueID, trackID string) (*models.Queue, error) {
params := map[string]string{
"track_id": trackID,
@@ -74,8 +72,7 @@ func (c *Client) RemoveFromQueue(ctx context.Context, queueID, trackID string) (
return &result, nil
}
// ReorderQueue reorders the queue
// PUT /queues/{queue_id}/reorder
// ReorderQueue reorders items in the queue from one position to another (PUT /queues/{queue_id}/reorder).
func (c *Client) ReorderQueue(ctx context.Context, queueID string, from, to int) (*models.Queue, error) {
params := map[string]string{
"from": fmt.Sprintf("%d", from),
@@ -90,15 +87,13 @@ func (c *Client) ReorderQueue(ctx context.Context, queueID string, from, to int)
return &result, nil
}
// ClearQueue clears the queue
// DELETE /queues/{queue_id}/clear
// ClearQueue clears the queue (DELETE /queues/{queue_id}/clear).
func (c *Client) ClearQueue(ctx context.Context, queueID string) error {
var result map[string]any
return c.request.Delete(ctx, fmt.Sprintf("/queues/%s/clear", queueID), nil, &result)
}
// NextTrack moves to the next track in the queue
// POST /queues/{queue_id}/next
// NextTrack moves to the next track in the queue (POST /queues/{queue_id}/next).
func (c *Client) NextTrack(ctx context.Context, queueID string) (*models.Queue, error) {
var result models.Queue
if err := c.request.Post(ctx, fmt.Sprintf("/queues/%s/next", queueID), nil, &result); err != nil {
@@ -108,8 +103,7 @@ func (c *Client) NextTrack(ctx context.Context, queueID string) (*models.Queue,
return &result, nil
}
// PreviousTrack moves to the previous track in the queue
// POST /queues/{queue_id}/prev
// PreviousTrack moves to the previous track in the queue (POST /queues/{queue_id}/prev).
func (c *Client) PreviousTrack(ctx context.Context, queueID string) (*models.Queue, error) {
var result models.Queue
if err := c.request.Post(ctx, fmt.Sprintf("/queues/%s/prev", queueID), nil, &result); err != nil {
@@ -119,8 +113,8 @@ func (c *Client) PreviousTrack(ctx context.Context, queueID string) (*models.Que
return &result, nil
}
// Seek seeks to a specific position in the current track (in milliseconds)
// POST /queues/{queue_id}/seek
// Seek seeks to a specific position in the current track (POST /queues/{queue_id}/seek).
// The positionMs parameter is the position in milliseconds.
func (c *Client) Seek(ctx context.Context, queueID string, positionMs int) (*models.Queue, error) {
params := map[string]string{
"position": fmt.Sprintf("%d", positionMs),
@@ -134,9 +128,8 @@ func (c *Client) Seek(ctx context.Context, queueID string, positionMs int) (*mod
return &result, nil
}
// SetRepeatMode sets the repeat mode for the queue
// mode can be "off", "one", or "all"
// POST /queues/{queue_id}/repeat
// SetRepeatMode sets the repeat mode for the queue (POST /queues/{queue_id}/repeat).
// The mode parameter can be "off", "one", or "all".
func (c *Client) SetRepeatMode(ctx context.Context, queueID, mode string) (*models.Queue, error) {
params := map[string]string{
"mode": mode,
@@ -150,8 +143,7 @@ func (c *Client) SetRepeatMode(ctx context.Context, queueID, mode string) (*mode
return &result, nil
}
// SetShuffle enables or disables shuffle for the queue
// POST /queues/{queue_id}/shuffle
// SetShuffle enables or disables shuffle for the queue (POST /queues/{queue_id}/shuffle).
func (c *Client) SetShuffle(ctx context.Context, queueID string, enabled bool) (*models.Queue, error) {
params := map[string]string{
"enabled": fmt.Sprintf("%t", enabled),
@@ -165,8 +157,8 @@ func (c *Client) SetShuffle(ctx context.Context, queueID string, enabled bool) (
return &result, nil
}
// SetVolume sets the volume for the queue (0-100)
// POST /queues/{queue_id}/volume
// SetVolume sets the volume for the queue (POST /queues/{queue_id}/volume).
// The volume parameter should be between 0 and 100.
func (c *Client) SetVolume(ctx context.Context, queueID string, volume int) (*models.Queue, error) {
params := map[string]string{
"volume": fmt.Sprintf("%d", volume),
@@ -180,8 +172,7 @@ func (c *Client) SetVolume(ctx context.Context, queueID string, volume int) (*mo
return &result, nil
}
// GetCurrentTrack gets the currently playing track from the queue
// GET /queues/{queue_id}/current
// GetCurrentTrack gets the currently playing track from the queue (GET /queues/{queue_id}/current).
func (c *Client) GetCurrentTrack(ctx context.Context, queueID string) (*models.QueueItem, error) {
var result models.QueueItem
if err := c.request.Get(ctx, fmt.Sprintf("/queues/%s/current", queueID), nil, &result); err != nil {
@@ -191,8 +182,7 @@ func (c *Client) GetCurrentTrack(ctx context.Context, queueID string) (*models.Q
return &result, nil
}
// GetQueueHistory gets the queue history (recently played tracks)
// GET /queues/{queue_id}/history
// GetQueueHistory gets the queue history (recently played tracks) (GET /queues/{queue_id}/history).
func (c *Client) GetQueueHistory(ctx context.Context, queueID string, limit int) ([]*models.QueueItem, error) {
params := map[string]string{
"limit": fmt.Sprintf("%d", limit),
@@ -211,7 +201,7 @@ func (c *Client) GetQueueHistory(ctx context.Context, queueID string, limit int)
return items, nil
}
// GetPlayContexts gets play contexts
// GetPlayContexts gets play contexts (GET /play-contexts).
func (c *Client) GetPlayContexts(ctx context.Context) ([]*models.PlayContext, error) {
var result []models.PlayContext
if err := c.request.Get(ctx, "/play-contexts", nil, &result); err != nil {
@@ -226,7 +216,7 @@ func (c *Client) GetPlayContexts(ctx context.Context) ([]*models.PlayContext, er
return contexts, nil
}
// GetPlayContextsData gets play contexts data
// GetPlayContextsData gets play contexts data (GET /play-contexts/data).
func (c *Client) GetPlayContextsData(ctx context.Context) (*models.PlayContextsData, error) {
var result models.PlayContextsData
if err := c.request.Get(ctx, "/play-contexts/data", nil, &result); err != nil {
internal/client/radio.go
+11 -16
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetRadioStations gets radio stations
// GetRadioStations gets radio stations (GET /radio/stations).
func (c *Client) GetRadioStations(ctx context.Context) ([]*models.RadioStation, error) {
var result []models.RadioStation
if err := c.request.Get(ctx, "/radio/stations", nil, &result); err != nil {
@@ -22,8 +23,7 @@ func (c *Client) GetRadioStations(ctx context.Context) ([]*models.RadioStation,
return stations, nil
}
// GetRadioStation gets a radio station by ID
// GET /rotor/station/{stationID}/info
// GetRadioStation gets a radio station by ID (GET /rotor/station/{stationID}/info).
func (c *Client) GetRadioStation(ctx context.Context, stationID string) (*models.RadioStation, error) {
var result models.RadioStation
if err := c.request.Get(ctx, fmt.Sprintf("/rotor/station/%s/info", stationID), nil, &result); err != nil {
@@ -33,8 +33,7 @@ func (c *Client) GetRadioStation(ctx context.Context, stationID string) (*models
return &result, nil
}
// GetStationTracks gets tracks for a radio station
// GET /rotor/station/{stationID}/tracks
// GetStationTracks gets tracks for a radio station (GET /rotor/station/{stationID}/tracks).
func (c *Client) GetStationTracks(ctx context.Context, stationID string, limit int) (*models.StationTracksResult, error) {
params := map[string]string{}
if limit > 0 {
@@ -48,7 +47,7 @@ func (c *Client) GetStationTracks(ctx context.Context, stationID string, limit i
return &result, nil
}
// GetRotorStations gets rotor stations (generative)
// GetRotorStations gets rotor stations (generative stations) (GET /rotor/stations).
func (c *Client) GetRotorStations(ctx context.Context) ([]*models.RotorStation, error) {
var result []models.RotorStation
if err := c.request.Get(ctx, "/rotor/stations", nil, &result); err != nil {
@@ -63,8 +62,7 @@ func (c *Client) GetRotorStations(ctx context.Context) ([]*models.RotorStation,
return stations, nil
}
// GetRotorStation gets a rotor station by ID
// GET /rotor/station/{stationID}/info
// GetRotorStation gets a rotor station by ID (GET /rotor/station/{stationID}/info).
func (c *Client) GetRotorStation(ctx context.Context, stationID string) (*models.RotorStation, error) {
var result models.RotorStation
if err := c.request.Get(ctx, fmt.Sprintf("/rotor/station/%s/info", stationID), nil, &result); err != nil {
@@ -74,8 +72,7 @@ func (c *Client) GetRotorStation(ctx context.Context, stationID string) (*models
return &result, nil
}
// GetRotorStationTracks gets tracks for a rotor station
// GET /rotor/station/{stationID}/tracks
// GetRotorStationTracks gets tracks for a rotor station (GET /rotor/station/{stationID}/tracks).
func (c *Client) GetRotorStationTracks(ctx context.Context, stationID string, limit int) (*models.RotorStationTracksResult, error) {
params := map[string]string{}
if limit > 0 {
@@ -89,8 +86,7 @@ func (c *Client) GetRotorStationTracks(ctx context.Context, stationID string, li
return &result, nil
}
// StartRotorSession starts a rotor session
// POST /rotor/station/{stationID}/session/start
// StartRotorSession starts a rotor session (POST /rotor/station/{stationID}/session/start).
func (c *Client) StartRotorSession(ctx context.Context, stationID string) (*models.RotorSession, error) {
var result models.RotorSession
if err := c.request.Post(ctx, fmt.Sprintf("/rotor/station/%s/session/start", stationID), nil, &result); err != nil {
@@ -100,8 +96,7 @@ func (c *Client) StartRotorSession(ctx context.Context, stationID string) (*mode
return &result, nil
}
// GetRotorSession gets rotor session info
// GET /rotor/session?session_id={sessionID}
// GetRotorSession gets rotor session info by session ID (GET /rotor/session).
func (c *Client) GetRotorSession(ctx context.Context, sessionID string) (*models.RotorSession, error) {
params := map[string]string{
"session_id": sessionID,
@@ -115,8 +110,8 @@ func (c *Client) GetRotorSession(ctx context.Context, sessionID string) (*models
return &result, nil
}
// RotorSessionFeedback sends feedback for a rotor session track
// POST /rotor/station/{stationID}/feedback
// RotorSessionFeedback sends feedback for a rotor session track (POST /rotor/station/{stationID}/feedback).
// The feedbackType parameter can be "like", "dislike", or "skip".
func (c *Client) RotorSessionFeedback(ctx context.Context, sessionID, trackID, feedbackType string) error {
params := map[string]string{
"track_id": trackID,
internal/client/request.go
+22 -13
View File
@@ -13,7 +13,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// Default values
// Default values for the Yandex Music API client.
const (
DefaultBaseURL = "https://api.music.yandex.net"
DefaultTimeout = 5 * time.Second
@@ -21,7 +21,7 @@ const (
DefaultClientHeader = "YandexMusicAndroid/24023621"
)
// RequestConfig holds configuration for the request client
// RequestConfig holds configuration for the request client.
type RequestConfig struct {
BaseURL string
Token string
@@ -36,14 +36,16 @@ type RequestConfig struct {
OnSchemaMismatch utils.SchemaMismatchHandler
}
// Request handles HTTP requests to Yandex Music API
// Request handles HTTP requests to the Yandex Music API.
// It manages the HTTP client, authentication headers, and request signing.
type Request struct {
config RequestConfig
client *http.Client
schemaTracker *utils.SchemaMismatchTracker
}
// NewRequest creates a new Request instance
// NewRequest creates a new Request instance with the given configuration.
// It sets up the HTTP client, default headers, and authentication if a token is provided.
func NewRequest(config RequestConfig) *Request {
if config.BaseURL == "" {
config.BaseURL = DefaultBaseURL
@@ -92,7 +94,8 @@ func NewRequest(config RequestConfig) *Request {
return r
}
// SetToken updates the authorization token
// SetToken updates the authorization token used for API requests.
// When a token is provided, it sets the Authorization header to "OAuth <token>".
func (r *Request) SetToken(token string) {
r.config.Token = token
if token != "" {
@@ -102,33 +105,38 @@ func (r *Request) SetToken(token string) {
}
}
// SetLanguage sets the Accept-Language header
// SetLanguage sets the Accept-Language header for API requests.
func (r *Request) SetLanguage(lang string) {
r.config.Language = lang
r.config.Headers["Accept-Language"] = lang
}
// Get performs a GET request
// Get performs a GET request to the given path with query parameters.
// The response is unmarshaled into the result pointer.
func (r *Request) Get(ctx context.Context, path string, params map[string]string, result any) error {
return r.doRequest(ctx, "GET", path, params, nil, result)
}
// Post performs a POST request
// Post performs a POST request to the given path with a JSON body.
// The response is unmarshaled into the result pointer.
func (r *Request) Post(ctx context.Context, path string, body any, result any) error {
return r.doRequest(ctx, "POST", path, nil, body, result)
}
// Put performs a PUT request
// Put performs a PUT request to the given path with a JSON body.
// The response is unmarshaled into the result pointer.
func (r *Request) Put(ctx context.Context, path string, body any, result any) error {
return r.doRequest(ctx, "PUT", path, nil, body, result)
}
// Delete performs a DELETE request
// Delete performs a DELETE request to the given path with an optional JSON body.
// The response is unmarshaled into the result pointer.
func (r *Request) Delete(ctx context.Context, path string, body any, result any) error {
return r.doRequest(ctx, "DELETE", path, nil, body, result)
}
// doRequest performs the actual HTTP request
// doRequest performs the actual HTTP request to the Yandex Music API.
// It handles URL building, request signing, response parsing, and error handling.
func (r *Request) doRequest(ctx context.Context, method, path string, params map[string]string, body any, result any) error {
// Build URL
fullURL := r.config.BaseURL + path
@@ -209,7 +217,7 @@ func (r *Request) doRequest(ctx context.Context, method, path string, params map
return nil
}
// handleErrorResponse handles HTTP error responses
// handleErrorResponse handles HTTP error responses by mapping status codes to typed errors.
func (r *Request) handleErrorResponse(statusCode int, body []byte) error {
var msg string
apiResp, err := utils.DeJSON(body)
@@ -235,7 +243,8 @@ func (r *Request) handleErrorResponse(statusCode int, body []byte) error {
}
}
// Download downloads a file from a URL
// Download downloads a file from the given URL and returns the raw response body.
// It is used for downloading track files and lyrics text.
func (r *Request) Download(ctx context.Context, urlStr string) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
if err != nil {
internal/client/search.go
+12 -10
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -7,7 +8,8 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// Search performs a multi-type search
// Search performs a multi-type search (GET /search).
// The searchType parameter specifies what to search for (e.g., "track", "album", "artist").
func (c *Client) Search(ctx context.Context, query string, searchType string, page, pageSize int) (*models.SearchResult, error) {
params := map[string]string{
"text": query,
@@ -46,7 +48,7 @@ func (c *Client) Search(ctx context.Context, query string, searchType string, pa
return &result, nil
}
// SearchTracks searches for tracks
// SearchTracks searches for tracks using Search with type "track".
func (c *Client) SearchTracks(ctx context.Context, query string, page, pageSize int) (*models.SearchTracksResult, error) {
result, err := c.Search(ctx, query, "track", page, pageSize)
if err != nil {
@@ -55,7 +57,7 @@ func (c *Client) SearchTracks(ctx context.Context, query string, page, pageSize
return result.Tracks, nil
}
// SearchAlbums searches for albums
// SearchAlbums searches for albums using Search with type "album".
func (c *Client) SearchAlbums(ctx context.Context, query string, page, pageSize int) (*models.SearchAlbumsResult, error) {
result, err := c.Search(ctx, query, "album", page, pageSize)
if err != nil {
@@ -64,7 +66,7 @@ func (c *Client) SearchAlbums(ctx context.Context, query string, page, pageSize
return result.Albums, nil
}
// SearchArtists searches for artists
// SearchArtists searches for artists using Search with type "artist".
func (c *Client) SearchArtists(ctx context.Context, query string, page, pageSize int) (*models.SearchArtistsResult, error) {
result, err := c.Search(ctx, query, "artist", page, pageSize)
if err != nil {
@@ -73,7 +75,7 @@ func (c *Client) SearchArtists(ctx context.Context, query string, page, pageSize
return result.Artists, nil
}
// SearchPlaylists searches for playlists
// SearchPlaylists searches for playlists using Search with type "playlist".
func (c *Client) SearchPlaylists(ctx context.Context, query string, page, pageSize int) (*models.SearchPlaylistsResult, error) {
result, err := c.Search(ctx, query, "playlist", page, pageSize)
if err != nil {
@@ -82,7 +84,7 @@ func (c *Client) SearchPlaylists(ctx context.Context, query string, page, pageSi
return result.Playlists, nil
}
// SearchVideos searches for videos
// SearchVideos searches for videos using Search with type "video".
func (c *Client) SearchVideos(ctx context.Context, query string, page, pageSize int) (*models.SearchVideosResult, error) {
result, err := c.Search(ctx, query, "video", page, pageSize)
if err != nil {
@@ -91,7 +93,7 @@ func (c *Client) SearchVideos(ctx context.Context, query string, page, pageSize
return result.Videos, nil
}
// SearchUsers searches for users
// SearchUsers searches for users using Search with type "user".
func (c *Client) SearchUsers(ctx context.Context, query string, page, pageSize int) (*models.SearchUsersResult, error) {
result, err := c.Search(ctx, query, "user", page, pageSize)
if err != nil {
@@ -100,7 +102,7 @@ func (c *Client) SearchUsers(ctx context.Context, query string, page, pageSize i
return result.Users, nil
}
// SearchSuggestions gets search suggestions
// SearchSuggestions gets search suggestions for a query (GET /search/suggest?type=suggest).
func (c *Client) SearchSuggestions(ctx context.Context, query string) ([]string, error) {
params := map[string]string{
"text": query,
@@ -116,7 +118,7 @@ func (c *Client) SearchSuggestions(ctx context.Context, query string) ([]string,
return result.Suggestions, nil
}
// SearchBanners gets search banners
// SearchBanners gets search banners for a query (GET /search/banner?type=banner).
func (c *Client) SearchBanners(ctx context.Context, query string) ([]models.SearchBanner, error) {
params := map[string]string{
"text": query,
@@ -132,7 +134,7 @@ func (c *Client) SearchBanners(ctx context.Context, query string) ([]models.Sear
return result.Banners, nil
}
// SearchTags gets search tags
// SearchTags gets search tags for a query (GET /search/tag?type=tag).
func (c *Client) SearchTags(ctx context.Context, query string) ([]models.Tag, error) {
params := map[string]string{
"text": query,
internal/client/settings.go
+8 -7
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -6,7 +7,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/models"
)
// GetSettings gets user settings
// GetSettings gets user settings (GET /account/settings).
func (c *Client) GetSettings(ctx context.Context) (*models.AccountSettings, error) {
var result models.AccountSettings
if err := c.request.Get(ctx, "/account/settings", nil, &result); err != nil {
@@ -15,7 +16,7 @@ func (c *Client) GetSettings(ctx context.Context) (*models.AccountSettings, erro
return &result, nil
}
// UpdateSettings updates user settings
// UpdateSettings updates user settings (PUT /account/settings).
func (c *Client) UpdateSettings(ctx context.Context, settings *models.AccountSettings) (*models.AccountSettings, error) {
var result models.AccountSettings
if err := c.request.Put(ctx, "/account/settings", settings, &result); err != nil {
@@ -24,7 +25,7 @@ func (c *Client) UpdateSettings(ctx context.Context, settings *models.AccountSet
return &result, nil
}
// GetExperiments gets experiments
// GetExperiments gets experiments (GET /experiments).
func (c *Client) GetExperiments(ctx context.Context) (*models.Experiments, error) {
var result models.Experiments
if err := c.request.Get(ctx, "/experiments", nil, &result); err != nil {
@@ -33,7 +34,7 @@ func (c *Client) GetExperiments(ctx context.Context) (*models.Experiments, error
return &result, nil
}
// GetExperimentDetails gets experiment details
// GetExperimentDetails gets experiment details for the given experiment ID (GET /experiments/details).
func (c *Client) GetExperimentDetails(ctx context.Context, experimentID string) (*models.ExperimentDetail, error) {
params := map[string]string{
"experiment_id": experimentID,
@@ -45,7 +46,7 @@ func (c *Client) GetExperimentDetails(ctx context.Context, experimentID string)
return &result, nil
}
// GetPermissions gets user permissions
// GetPermissions gets user permissions (GET /permissions).
func (c *Client) GetPermissions(ctx context.Context) (*models.Permissions, error) {
var result models.Permissions
if err := c.request.Get(ctx, "/permissions", nil, &result); err != nil {
@@ -54,7 +55,7 @@ func (c *Client) GetPermissions(ctx context.Context) (*models.Permissions, error
return &result, nil
}
// GetPermissionAlerts gets permission alerts
// GetPermissionAlerts gets permission alerts (GET /permission-alerts).
func (c *Client) GetPermissionAlerts(ctx context.Context) (*models.PermissionAlerts, error) {
var result models.PermissionAlerts
if err := c.request.Get(ctx, "/permission-alerts", nil, &result); err != nil {
@@ -63,7 +64,7 @@ func (c *Client) GetPermissionAlerts(ctx context.Context) (*models.PermissionAle
return &result, nil
}
// GetContentRestrictions gets content restrictions
// GetContentRestrictions gets content restrictions (GET /content-restrictions).
func (c *Client) GetContentRestrictions(ctx context.Context) (*models.ContentRestrictions, error) {
var result models.ContentRestrictions
if err := c.request.Get(ctx, "/content-restrictions", nil, &result); err != nil {
internal/client/supplements.go
+20 -21
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -9,8 +10,7 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// GetTrackSupplement gets supplement for a track
// GET /tracks/{track_id}/supplement
// GetTrackSupplement gets supplement for a track (GET /tracks/{track_id}/supplement).
func (c *Client) GetTrackSupplement(ctx context.Context, trackID string) (*models.Supplement, error) {
path := fmt.Sprintf("/tracks/%s/supplement", trackID)
@@ -21,8 +21,9 @@ func (c *Client) GetTrackSupplement(ctx context.Context, trackID string) (*model
return &result, nil
}
// GetTrackLyrics gets lyrics for a track (new endpoint with signing)
// GET /tracks/{track_id}/lyrics
// GetTrackLyrics gets lyrics for a track (GET /tracks/{track_id}/lyrics).
// The format parameter specifies the lyrics format (e.g., "TEXT" or "LRC").
// The request is signed using the default signing key.
func (c *Client) GetTrackLyrics(ctx context.Context, trackID string, format string) (*models.TrackLyrics, error) {
path := fmt.Sprintf("/tracks/%s/lyrics", trackID)
@@ -42,7 +43,7 @@ func (c *Client) GetTrackLyrics(ctx context.Context, trackID string, format stri
return &result, nil
}
// GetTrackLyricsText fetches the full lyrics text from the download URL
// GetTrackLyricsText fetches the full lyrics text from the download URL provided in TrackLyrics.
func (c *Client) GetTrackLyricsText(ctx context.Context, trackLyrics *models.TrackLyrics) (string, error) {
data, err := c.request.Download(ctx, trackLyrics.DownloadURL)
if err != nil {
@@ -51,8 +52,7 @@ func (c *Client) GetTrackLyricsText(ctx context.Context, trackLyrics *models.Tra
return string(data), nil
}
// GetLyrics gets lyrics info for a track (legacy endpoint)
// GET /tracks/lyrics?track_id={track_id}
// GetLyrics gets lyrics info for a track using the legacy endpoint (GET /tracks/lyrics).
func (c *Client) GetLyrics(ctx context.Context, trackID string) (*models.LyricsInfo, error) {
params := map[string]string{
"track_id": trackID,
@@ -65,8 +65,7 @@ func (c *Client) GetLyrics(ctx context.Context, trackID string) (*models.LyricsI
return &result, nil
}
// GetVideoSupplement gets video supplement for a track (legacy endpoint)
// GET /tracks/video-supplement?track_id={track_id}
// GetVideoSupplement gets video supplement for a track using the legacy endpoint (GET /tracks/video-supplement).
func (c *Client) GetVideoSupplement(ctx context.Context, trackID string) (*models.VideoSupplement, error) {
params := map[string]string{
"track_id": trackID,
@@ -79,44 +78,43 @@ func (c *Client) GetVideoSupplement(ctx context.Context, trackID string) (*model
return &result, nil
}
// GetLyricsByTrackID is an alias for GetTrackLyrics for backward compatibility
// GET /tracks/{track_id}/lyrics
// GetLyricsByTrackID is an alias for GetTrackLyrics for backward compatibility (GET /tracks/{track_id}/lyrics).
func (c *Client) GetLyricsByTrackID(ctx context.Context, trackID string, format string) (*models.TrackLyrics, error) {
return c.GetTrackLyrics(ctx, trackID, format)
}
// LyricsFormat represents the lyrics format
// LyricsFormat represents the lyrics format.
type LyricsFormat string
const (
// LyricsFormatText is plain text format
// LyricsFormatText is plain text lyrics format.
LyricsFormatText LyricsFormat = "TEXT"
// LyricsFormatLRC is LRC format with timestamps
// LyricsFormatLRC is LRC format lyrics with timestamps.
LyricsFormatLRC LyricsFormat = "LRC"
)
// GetTrackLyricsWithOptions gets lyrics with options
// GetTrackLyricsWithOptions gets lyrics with options using a LyricsFormat value.
func (c *Client) GetTrackLyricsWithOptions(ctx context.Context, trackID string, format LyricsFormat) (*models.TrackLyrics, error) {
return c.GetTrackLyrics(ctx, trackID, string(format))
}
// SupplementOptions holds options for supplement requests
// SupplementOptions holds options for supplement requests.
type SupplementOptions struct {
TrackID string
}
// GetSupplement gets track supplement with options
// GetSupplement gets track supplement with options.
func (c *Client) GetSupplement(ctx context.Context, opts SupplementOptions) (*models.Supplement, error) {
return c.GetTrackSupplement(ctx, opts.TrackID)
}
// LyricsOptions holds options for lyrics requests
// LyricsOptions holds options for lyrics requests.
type LyricsOptions struct {
TrackID string
Format LyricsFormat
}
// GetLyricsWithOptions gets track lyrics with options
// GetLyricsWithOptions gets track lyrics with options.
func (c *Client) GetLyricsWithOptions(ctx context.Context, opts LyricsOptions) (*models.TrackLyrics, error) {
format := string(opts.Format)
if format == "" {
@@ -125,13 +123,14 @@ func (c *Client) GetLyricsWithOptions(ctx context.Context, opts LyricsOptions) (
return c.GetTrackLyrics(ctx, opts.TrackID, format)
}
// Sign represents a request signature
// Sign represents a request signature for signed API requests.
type Sign struct {
Timestamp int64
Value string
}
// GetSignRequest creates a signature for a track request (exported for external use)
// GetSignRequest creates a signature for a track request (exported for external use).
// It delegates to utils.GetSignRequest with the default signing key.
func GetSignRequest(trackID string) Sign {
h := utils.GetSignRequest(trackID, utils.DefaultSignKey)
internal/client/tracks.go
+11 -6
View File
@@ -1,3 +1,4 @@
// Package client provides methods for interacting with Yandex Music API endpoints.
package client
import (
@@ -8,7 +9,8 @@ import (
"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
)
// GetTracks gets tracks by IDs
// GetTracks gets tracks by their IDs (GET /tracks).
// Returns a slice of Track pointers, or nil if no IDs are provided.
func (c *Client) GetTracks(ctx context.Context, trackIDs []string) ([]*models.Track, error) {
if len(trackIDs) == 0 {
return nil, nil
@@ -31,7 +33,8 @@ func (c *Client) GetTracks(ctx context.Context, trackIDs []string) ([]*models.Tr
return tracks, nil
}
// GetTrack gets a single track by ID
// GetTrack gets a single track by ID using GetTracks.
// Returns an error if no track is found with the given ID.
func (c *Client) GetTrack(ctx context.Context, trackID string) (*models.Track, error) {
tracks, err := c.GetTracks(ctx, []string{trackID})
if err != nil {
@@ -43,7 +46,8 @@ func (c *Client) GetTrack(ctx context.Context, trackID string) (*models.Track, e
return tracks[0], nil
}
// GetTrackDownloadInfo gets download info for a track
// GetTrackDownloadInfo gets download info for a track (GET /tracks/{track_id}/download-info).
// The quality parameter specifies the desired audio quality (e.g., "mp3").
func (c *Client) GetTrackDownloadInfo(ctx context.Context, trackID, quality string) ([]models.DownloadInfo, error) {
// This requires signing - use the sign utility
// For now, return basic implementation
@@ -58,7 +62,8 @@ func (c *Client) GetTrackDownloadInfo(ctx context.Context, trackID, quality stri
return result, nil
}
// DownloadTrack downloads a track
// DownloadTrack downloads a track by ID.
// It first fetches download info, finds a matching format/bitrate, then downloads the file content.
func (c *Client) DownloadTrack(ctx context.Context, trackID, format string, bitrate int) ([]byte, error) {
info, err := c.GetTrackDownloadInfo(ctx, trackID, format)
if err != nil {
@@ -85,12 +90,12 @@ func (c *Client) DownloadTrack(ctx context.Context, trackID, format string, bitr
return c.request.Download(ctx, url)
}
// SearchResult represents search results
// SearchResult represents search results containing tracks.
type SearchResult struct {
Tracks *SearchTracksResult `json:"tracks"`
}
// SearchTracksResult represents track search results
// SearchTracksResult represents track search results with total count and results list.
type SearchTracksResult struct {
Total int `json:"total"`
Results []models.Track `json:"results"`