Merge pull request #5 from joshraphael/issue/4

issue-4: Add get user game leaderboards endpoint

Author: joshraphael

README.md

@@ -88,6 +88,7 @@ For convenience, the API docs and examples can be found in the tables below
 |-|-|-|
 |`GetGameLeaderboards()`|Gets a given games's list of leaderboards.|[docs](https://api-docs.retroachievements.org/v1/get-game-leaderboards.html) \| [example](examples/leaderboards/getgameleaderboards/getgameleaderboards.go)|
 |`GetLeaderboardEntries()`|Gets a given leadboard's entries.|[docs](https://api-docs.retroachievements.org/v1/get-leaderboard-entries.html) \| [example](examples/leaderboards/getleaderboardentries/getleaderboardentries.go)|
+|`GetUserGameLeaderboards()`|Gets a user's list of leaderboards for a given game.|[docs](https://api-docs.retroachievements.org/v1/get-user-game-leaderboards.html) \| [example](examples/leaderboards/getusergameleaderboards/getusergameleaderboards.go)|
 
 <h3>System</h3>
 

assets/ra_gopher_big_banner.png

@@ -0,0 +1,29 @@
+// Package getusergameleaderboards provides an example for getting a user's list of leaderboards for a given game.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/joshraphael/go-retroachievements"
+	"github.com/joshraphael/go-retroachievements/models"
+)
+
+/*
+Test script, add RA_API_KEY to your env and use `go run getusergameleaderboards.go`
+*/
+func main() {
+	secret := os.Getenv("RA_API_KEY")
+
+	client := retroachievements.NewClient(secret)
+
+	resp, err := client.GetUserGameLeaderboards(models.GetUserGameLeaderboardsParameters{
+		GameID:   583,
+		Username: "joshraphael",
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("%+v\n", resp)
+}

examples/leaderboards/getusergameleaderboards/getusergameleaderboards.go

@@ -60,3 +60,30 @@ func (c *Client) GetLeaderboardEntries(params models.GetLeaderboardEntriesParame
 	}
 	return resp, nil
 }
+
+// GetUserGameLeaderboards gets a user's list of leaderboards for a given game.
+func (c *Client) GetUserGameLeaderboards(params models.GetUserGameLeaderboardsParameters) (*models.GetUserGameLeaderboards, error) {
+	details := []raHttp.RequestDetail{
+		raHttp.Method(http.MethodGet),
+		raHttp.UserAgent(c.UserAgent),
+		raHttp.Path("/API/API_GetUserGameLeaderboards.php"),
+		raHttp.APIToken(c.Secret),
+		raHttp.U(params.Username),
+		raHttp.I([]string{strconv.Itoa(params.GameID)}),
+	}
+	if params.Count != nil {
+		details = append(details, raHttp.C(*params.Count))
+	}
+	if params.Offset != nil {
+		details = append(details, raHttp.O(*params.Offset))
+	}
+	r, err := c.do(details...)
+	if err != nil {
+		return nil, fmt.Errorf("calling endpoint: %w", err)
+	}
+	resp, err := raHttp.ResponseObject[models.GetUserGameLeaderboards](r)
+	if err != nil {
+		return nil, fmt.Errorf("parsing response object: %w", err)
+	}
+	return resp, nil
+}

leaderboards.go

@@ -242,6 +242,14 @@ func TestGetLeaderboardEntries(tt *testing.T) {
 			},
 			assert: func(t *testing.T, resp *models.GetLeaderboardEntries, err error) {
 				require.NotNil(t, resp)
+				require.Equal(t, 1, resp.Count)
+				require.Equal(t, 2, resp.Total)
+				require.Len(t, resp.Results, 1)
+				require.Equal(t, "ramenoid", resp.Results[0].User)
+				require.Equal(t, dateSubmitted, resp.Results[0].DateSubmitted.Time)
+				require.Equal(t, 1908730, resp.Results[0].Score)
+				require.Equal(t, "1,908,730", resp.Results[0].FormattedScore)
+				require.Equal(t, 1, resp.Results[0].Rank)
 				require.NoError(t, err)
 			},
 		},
@@ -270,3 +278,149 @@ func TestGetLeaderboardEntries(tt *testing.T) {
 		})
 	}
 }
+
+func TestGetUserGameLeaderboards(tt *testing.T) {
+	count := 10
+	offset := 10
+	dateUpdated, err := time.Parse(models.RFC3339NumColonTZFormat, "2024-10-05T18:30:59+00:00")
+	require.NoError(tt, err)
+	tests := []struct {
+		name            string
+		params          models.GetUserGameLeaderboardsParameters
+		modifyURL       func(url string) string
+		responseCode    int
+		responseMessage models.GetUserGameLeaderboards
+		responseError   models.ErrorResponse
+		response        func(messageBytes []byte, errorBytes []byte) []byte
+		assert          func(t *testing.T, resp *models.GetUserGameLeaderboards, err error)
+	}{
+		{
+			name: "fail to call endpoint",
+			params: models.GetUserGameLeaderboardsParameters{
+				GameID:   515,
+				Username: "test",
+				Count:    &count,
+				Offset:   &offset,
+			},
+			modifyURL: func(url string) string {
+				return ""
+			},
+			responseCode: http.StatusOK,
+			response: func(messageBytes []byte, errorBytes []byte) []byte {
+				return messageBytes
+			},
+			assert: func(t *testing.T, resp *models.GetUserGameLeaderboards, err error) {
+				require.Nil(t, resp)
+				require.EqualError(t, err, "calling endpoint: Get \"/API/API_GetUserGameLeaderboards.php?c=10&i=515&o=10&u=test&y=some_secret\": unsupported protocol scheme \"\"")
+			},
+		},
+		{
+			name: "error response",
+			params: models.GetUserGameLeaderboardsParameters{
+				GameID:   515,
+				Username: "test",
+				Count:    &count,
+				Offset:   &offset,
+			},
+			modifyURL: func(url string) string {
+				return url
+			},
+			responseCode: http.StatusUnauthorized,
+			responseError: models.ErrorResponse{
+				Message: "test",
+				Errors: []models.ErrorDetail{
+					{
+						Status: http.StatusUnauthorized,
+						Code:   "unauthorized",
+						Title:  "Not Authorized",
+					},
+				},
+			},
+			response: func(messageBytes []byte, errorBytes []byte) []byte {
+				return errorBytes
+			},
+			assert: func(t *testing.T, resp *models.GetUserGameLeaderboards, err error) {
+				require.Nil(t, resp)
+				require.EqualError(t, err, "parsing response object: error code 401 returned: {\"message\":\"test\",\"errors\":[{\"status\":401,\"code\":\"unauthorized\",\"title\":\"Not Authorized\"}]}")
+			},
+		},
+		{
+			name: "success",
+			params: models.GetUserGameLeaderboardsParameters{
+				GameID:   515,
+				Username: "test",
+				Count:    &count,
+				Offset:   &offset,
+			},
+			modifyURL: func(url string) string {
+				return url
+			},
+			responseCode: http.StatusOK,
+			responseMessage: models.GetUserGameLeaderboards{
+				Count: 1,
+				Total: 2,
+				Results: []models.GetUserGameLeaderboardsResult{
+					{
+						ID:          114798,
+						RankAsc:     true,
+						Title:       "Speedrun Monster Max",
+						Description: "Complete the game from start to finish as fast as possible without using passwords",
+						Format:      "TIME",
+						UserEntry: models.GetUserGameLeaderboardsUserEntry{
+							User: "ramenoid",
+							DateUpdated: models.RFC3339NumColonTZ{
+								Time: dateUpdated,
+							},
+							Score:          1908730,
+							FormattedScore: "1,908,730",
+							Rank:           1,
+						},
+					},
+				},
+			},
+			response: func(messageBytes []byte, errorBytes []byte) []byte {
+				return messageBytes
+			},
+			assert: func(t *testing.T, resp *models.GetUserGameLeaderboards, err error) {
+				require.NotNil(t, resp)
+				require.Equal(t, 1, resp.Count)
+				require.Equal(t, 2, resp.Total)
+				require.Len(t, resp.Results, 1)
+				require.Equal(t, 114798, resp.Results[0].ID)
+				require.True(t, resp.Results[0].RankAsc)
+				require.Equal(t, "Speedrun Monster Max", resp.Results[0].Title)
+				require.Equal(t, "Complete the game from start to finish as fast as possible without using passwords", resp.Results[0].Description)
+				require.Equal(t, "TIME", resp.Results[0].Format)
+				require.Equal(t, "ramenoid", resp.Results[0].UserEntry.User)
+				require.Equal(t, 1908730, resp.Results[0].UserEntry.Score)
+				require.Equal(t, "1,908,730", resp.Results[0].UserEntry.FormattedScore)
+				require.Equal(t, 1, resp.Results[0].UserEntry.Rank)
+				require.Equal(t, dateUpdated, resp.Results[0].UserEntry.DateUpdated.Time)
+				require.NoError(t, err)
+			},
+		},
+	}
+	for _, test := range tests {
+		tt.Run(test.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				expectedPath := "/API/API_GetUserGameLeaderboards.php"
+				if r.URL.Path != expectedPath {
+					t.Errorf("Expected to request '%s', got: %s", expectedPath, r.URL.Path)
+				}
+				w.WriteHeader(test.responseCode)
+				messageBytes, err := json.Marshal(test.responseMessage)
+				require.NoError(t, err)
+				errBytes, err := json.Marshal(test.responseError)
+				require.NoError(t, err)
+				resp := test.response(messageBytes, errBytes)
+				num, err := w.Write(resp)
+				require.NoError(t, err)
+				require.Equal(t, num, len(resp))
+			}))
+			defer server.Close()
+			client := retroachievements.New(test.modifyURL(server.URL), "go-retroachievements/v0.0.0", "some_secret")
+			resp, err := client.GetUserGameLeaderboards(test.params)
+			test.assert(t, resp, err)
+		})
+	}
+}

leaderboards_test.go

@@ -56,3 +56,40 @@ type GetLeaderboardEntriesResult struct {
 	FormattedScore string            `json:"FormattedScore"`
 	DateSubmitted  RFC3339NumColonTZ `json:"DateSubmitted"`
 }
+
+type GetUserGameLeaderboardsParameters struct {
+	// The target username
+	Username string
+
+	// The target game ID
+	GameID int
+
+	// [Optional] The number of records to return (default: 100, max: 500).
+	Count *int
+
+	// [Optional] The number of entries to skip (default: 0).
+	Offset *int
+}
+
+type GetUserGameLeaderboards struct {
+	Count   int                             `json:"Count"`
+	Total   int                             `json:"Total"`
+	Results []GetUserGameLeaderboardsResult `json:"Results"`
+}
+
+type GetUserGameLeaderboardsResult struct {
+	ID          int                              `json:"ID"`
+	RankAsc     bool                             `json:"RankAsc"`
+	Title       string                           `json:"Title"`
+	Description string                           `json:"Description"`
+	Format      string                           `json:"Format"`
+	UserEntry   GetUserGameLeaderboardsUserEntry `json:"UserEntry"`
+}
+
+type GetUserGameLeaderboardsUserEntry struct {
+	Rank           int               `json:"Rank"`
+	User           string            `json:"User"`
+	Score          int               `json:"Score"`
+	FormattedScore string            `json:"FormattedScore"`
+	DateUpdated    RFC3339NumColonTZ `json:"DateUpdated"`
+}