Clean up Hierarchy function parameters

client.go

@@ -1473,24 +1473,10 @@ func (cli *Client) JoinedRooms() (resp *RespJoinedRooms, err error) {
 // The hierarchy API is provided to walk the space tree and discover the rooms with their aesthetic details. works in a depth-first manner:
 // when it encounters another space as a child it recurses into that space before returning non-space children.
 //
-// NOTE: Only the roomID is required, the rest of the fields are optional and ignored if left to default values.
-func (cli *Client) Hierarchy(roomID id.RoomID, from string, max_depth int, suggested_only bool, limit int) (resp *RespHierarchy, err error) {
-	query := map[string]string{}
-	if from != "" {
-		query["from"] = from
-	}
-	if limit > 0 {
-		query["limit"] = strconv.Itoa(limit)
-	}
-	if max_depth > 0 {
-		query["max_depth"] = strconv.Itoa(max_depth)
-	}
-	if suggested_only {
-		query["suggested_only"] = "true"
-	}
-
-	urlPath := cli.BuildURLWithQuery(ClientURLPath{"v1", "rooms", roomID, "hierarchy"}, query)
-	_, err = cli.MakeRequest("GET", urlPath, nil, &resp)
+// The second function parameter specifies query parameters to limit the response. No query parameters will be added if it's nil.
+func (cli *Client) Hierarchy(roomID id.RoomID, req *ReqHierarchy) (resp *RespHierarchy, err error) {
+	urlPath := cli.BuildURLWithQuery(ClientURLPath{"v1", "rooms", roomID, "hierarchy"}, req.Query())
+	_, err = cli.MakeRequest(http.MethodGet, urlPath, nil, &resp)
 	return
 }
 

requests.go

@@ -2,6 +2,7 @@ package mautrix
 
 import (
 	"encoding/json"
+	"strconv"
 
 	"maunium.net/go/mautrix/event"
 	"maunium.net/go/mautrix/id"
@@ -340,3 +341,41 @@ type ReqSetReadMarkers struct {
 	BeeperReadPrivateExtra interface{} `json:"com.beeper.read.private.extra"`
 	BeeperFullyReadExtra   interface{} `json:"com.beeper.fully_read.extra"`
 }
+
+// ReqHierarchy contains the parameters for https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv1roomsroomidhierarchy
+//
+// As it's a GET method, there is no JSON body, so this is only query parameters.
+type ReqHierarchy struct {
+	// A pagination token from a previous Hierarchy call.
+	// If specified, max_depth and suggested_only cannot be changed from the first request.
+	From string
+	// Limit for the maximum number of rooms to include per response.
+	// The server will apply a default value if a limit isn't provided.
+	Limit int
+	// Limit for how far to go into the space. When reached, no further child rooms will be returned.
+	// The server will apply a default value if a max depth isn't provided.
+	MaxDepth *int
+	// Flag to indicate whether the server should only consider suggested rooms.
+	// Suggested rooms are annotated in their m.space.child event contents.
+	SuggestedOnly bool
+}
+
+func (req *ReqHierarchy) Query() map[string]string {
+	query := map[string]string{}
+	if req == nil {
+		return query
+	}
+	if req.From != "" {
+		query["from"] = req.From
+	}
+	if req.Limit > 0 {
+		query["limit"] = strconv.Itoa(req.Limit)
+	}
+	if req.MaxDepth != nil {
+		query["max_depth"] = strconv.Itoa(*req.MaxDepth)
+	}
+	if req.SuggestedOnly {
+		query["suggested_only"] = "true"
+	}
+	return query
+}