add GetUserCompletionProgress endpoint

README.md

@@ -51,6 +51,7 @@ For convenience, the API docs and examples can be found in the tables below
 |`GetAchievementsEarnedBetween(string,Time,Time)`|Get a list of achievements earned by a user between two dates.|[docs](https://api-docs.retroachievements.org/v1/get-achievements-earned-between.html) \| [example](examples/user/getachievementsearnedbetween/getachievementsearnedbetween.go)|
 |`GetAchievementsEarnedOnDay(string,Time)`|Get a list of achievements earned by a user on a given date.|[docs](https://api-docs.retroachievements.org/v1/get-achievements-earned-on-day.html) \| [example](examples/user/getachievementsearnedonday/getachievementsearnedonday.go)|
 |`GetGameInfoAndUserProgress(string,int,bool)`|Get metadata about a game as well as a user's progress on that game.|[docs](https://api-docs.retroachievements.org/v1/get-game-info-and-user-progress.html) \| [example](examples/user/getgameinfoanduserprogress/getgameinfoanduserprogress.go)|
+|`GetUserCompletionProgress(string)`|Get metadata about all the user's played games and any awards associated with them.|[docs](https://api-docs.retroachievements.org/v1/get-user-completion-progress.html) \| [example](examples/user/getusercompletionprogress/getusercompletionprogress.go)|
 
 <h3>Game</h3>
 

examples/user/getusercompletionprogress/getusercompletionprogress.go

@@ -0,0 +1,25 @@
+// Package getusercompletionprogress provides an example for getting a users profile
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/joshraphael/go-retroachievements"
+)
+
+/*
+Test script, add RA_API_KEY to your env and use `go run getusercompletionprogress.go`
+*/
+func main() {
+	secret := os.Getenv("RA_API_KEY")
+
+	client := retroachievements.NewClient(secret)
+
+	resp, err := client.GetUserCompletionProgress("joshraphael")
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("%+v\n", resp)
+}

models/game.go

@@ -56,3 +56,23 @@ type UserGameProgress struct {
 	HighestAwardKind         *string            `json:"HighestAwardKind"`
 	HighestAwardDate         *RFC3339NumColonTZ `json:"HighestAwardDate"`
 }
+
+type UserCompletionProgress struct {
+	Count   int                  `json:"Count"`
+	Total   int                  `json:"Total"`
+	Results []CompletionProgress `json:"Results"`
+}
+
+type CompletionProgress struct {
+	GameID                int                `json:"GameID"`
+	Title                 string             `json:"Title"`
+	ImageIcon             string             `json:"ImageIcon"`
+	ConsoleID             int                `json:"ConsoleID"`
+	ConsoleName           string             `json:"ConsoleName"`
+	MaxPossible           int                `json:"MaxPossible"`
+	NumAwarded            int                `json:"NumAwarded"`
+	NumAwardedHardcore    int                `json:"NumAwardedHardcore"`
+	MostRecentAwardedDate RFC3339NumColonTZ  `json:"MostRecentAwardedDate"`
+	HighestAwardKind      *string            `json:"HighestAwardKind"`
+	HighestAwardDate      *RFC3339NumColonTZ `json:"HighestAwardDate"`
+}

user.go

@@ -104,3 +104,21 @@ func (c *Client) GetGameInfoAndUserProgress(username string, game int, includeAw
 	}
 	return gameProgress, nil
 }
+
+// GetUserCompletionProgress get metadata about all the user's played games and any awards associated with them.
+func (c *Client) GetUserCompletionProgress(username string) (*models.UserCompletionProgress, error) {
+	resp, err := c.do(
+		raHttp.Method(http.MethodGet),
+		raHttp.Path("/API/API_GetUserCompletionProgress.php"),
+		raHttp.APIToken(c.Secret),
+		raHttp.Username(username),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("calling endpoint: %w", err)
+	}
+	completionProgress, err := raHttp.ResponseObject[models.UserCompletionProgress](resp)
+	if err != nil {
+		return nil, fmt.Errorf("parsing response object: %w", err)
+	}
+	return completionProgress, nil
+}

user_test.go

@@ -833,3 +833,146 @@ func TestGetGameInfoAndUserProgress(tt *testing.T) {
 		})
 	}
 }
+
+func TestGetUserCompletionProgress(tt *testing.T) {
+	highestAwardKind := "mastered"
+	awarded, err := time.Parse(models.RFC3339NumColonTZFormat, "2024-05-07T08:48:54+00:00")
+	require.NoError(tt, err)
+	tests := []struct {
+		name                           string
+		username                       string
+		modifyURL                      func(url string) string
+		responseCode                   int
+		responseUserCompletionProgress models.UserCompletionProgress
+		responseError                  models.ErrorResponse
+		response                       func(userCompletionProgressBytes []byte, errorBytes []byte) []byte
+		assert                         func(t *testing.T, completionProgress *models.UserCompletionProgress, err error)
+	}{
+		{
+			name:     "fail to call endpoint",
+			username: "Test",
+			modifyURL: func(url string) string {
+				return ""
+			},
+			responseCode: http.StatusUnauthorized,
+			responseError: models.ErrorResponse{
+				Message: "test",
+				Errors: []models.ErrorDetail{
+					{
+						Status: http.StatusUnauthorized,
+						Code:   "unauthorized",
+						Title:  "Not Authorized",
+					},
+				},
+			},
+			response: func(userCompletionProgressBytes []byte, errorBytes []byte) []byte {
+				return errorBytes
+			},
+			assert: func(t *testing.T, completionProgress *models.UserCompletionProgress, err error) {
+				require.Nil(t, completionProgress)
+				require.EqualError(t, err, "calling endpoint: Get \"/API/API_GetUserCompletionProgress.php?u=Test&y=some_secret\": unsupported protocol scheme \"\"")
+			},
+		},
+		{
+			name:     "error response",
+			username: "Test",
+			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(userCompletionProgressBytes []byte, errorBytes []byte) []byte {
+				return errorBytes
+			},
+			assert: func(t *testing.T, completionProgress *models.UserCompletionProgress, err error) {
+				require.Nil(t, completionProgress)
+				require.EqualError(t, err, "parsing response object: error responses: [401] Not Authorized")
+			},
+		},
+		{
+			name:     "success",
+			username: "Test",
+			modifyURL: func(url string) string {
+				return url
+			},
+			responseCode: http.StatusOK,
+			responseUserCompletionProgress: models.UserCompletionProgress{
+				Count: 19,
+				Total: 18,
+				Results: []models.CompletionProgress{
+					{
+						GameID:             14068,
+						Title:              "Donkey Kong",
+						ImageIcon:          "/Images/044908.png",
+						ConsoleID:          44,
+						ConsoleName:        "ColecoVision",
+						MaxPossible:        19,
+						NumAwarded:         13,
+						NumAwardedHardcore: 13,
+						MostRecentAwardedDate: models.RFC3339NumColonTZ{
+							Time: awarded,
+						},
+						HighestAwardKind: &highestAwardKind,
+						HighestAwardDate: &models.RFC3339NumColonTZ{
+							Time: awarded,
+						},
+					},
+				},
+			},
+			response: func(userCompletionProgressBytes []byte, errorBytes []byte) []byte {
+				return userCompletionProgressBytes
+			},
+			assert: func(t *testing.T, completionProgress *models.UserCompletionProgress, err error) {
+				require.NotNil(t, completionProgress)
+				require.Equal(t, 19, completionProgress.Count)
+				require.Equal(t, 18, completionProgress.Total)
+				require.Len(t, completionProgress.Results, 1)
+				require.Equal(t, 14068, completionProgress.Results[0].GameID)
+				require.Equal(t, "Donkey Kong", completionProgress.Results[0].Title)
+				require.Equal(t, "/Images/044908.png", completionProgress.Results[0].ImageIcon)
+				require.Equal(t, 44, completionProgress.Results[0].ConsoleID)
+				require.Equal(t, "ColecoVision", completionProgress.Results[0].ConsoleName)
+				require.Equal(t, 19, completionProgress.Results[0].MaxPossible)
+				require.Equal(t, 13, completionProgress.Results[0].NumAwarded)
+				require.Equal(t, 13, completionProgress.Results[0].NumAwardedHardcore)
+				require.Equal(t, awarded, completionProgress.Results[0].MostRecentAwardedDate.Time)
+				require.Equal(t, highestAwardKind, *completionProgress.Results[0].HighestAwardKind)
+				require.Equal(t, awarded, completionProgress.Results[0].HighestAwardDate.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_GetUserCompletionProgress.php"
+				if r.URL.Path != expectedPath {
+					t.Errorf("Expected to request '%s', got: %s", expectedPath, r.URL.Path)
+				}
+				w.WriteHeader(test.responseCode)
+				gameProgressBytes, err := json.Marshal(test.responseUserCompletionProgress)
+				require.NoError(t, err)
+				errBytes, err := json.Marshal(test.responseError)
+				require.NoError(t, err)
+				resp := test.response(gameProgressBytes, 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), "some_secret")
+			userCompletionProgress, err := client.GetUserCompletionProgress(test.username)
+			test.assert(t, userCompletionProgress, err)
+		})
+	}
+}