From d83b63aeaf642d537e7d6755893323ee41ac7dff Mon Sep 17 00:00:00 2001
From: nexy7574 <git@nexy7574.co.uk>
Date: Sun, 9 Mar 2025 17:16:31 +0000
Subject: [PATCH] client: add wrapper for /knock endpoint (#359)

---
 client.go    | 22 ++++++++++++++++++++++
 requests.go  |  5 +++++
 responses.go |  5 +++++
 3 files changed, 32 insertions(+)

diff --git a/client.go b/client.go
index e6757d67..7b5a7fe4 100644
--- a/client.go
+++ b/client.go
@@ -974,6 +974,28 @@ func (cli *Client) JoinRoom(ctx context.Context, roomIDorAlias string, req *ReqJ
 	return
 }
 
+// KnockRoom requests to join a room ID or alias. See https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3knockroomidoralias
+//
+// The last parameter contains optional extra fields and can be left nil.
+func (cli *Client) KnockRoom(ctx context.Context, roomIDorAlias string, req *ReqKnockRoom) (resp *RespKnockRoom, err error) {
+	if req == nil {
+		req = &ReqKnockRoom{}
+	}
+	urlPath := cli.BuildURLWithFullQuery(ClientURLPath{"v3", "knock", roomIDorAlias}, func(q url.Values) {
+		if len(req.Via) > 0 {
+			q["via"] = req.Via
+		}
+	})
+	_, err = cli.MakeRequest(ctx, http.MethodPost, urlPath, req, &resp)
+	if err == nil && cli.StateStore != nil {
+		err = cli.StateStore.SetMembership(ctx, resp.RoomID, cli.UserID, event.MembershipKnock)
+		if err != nil {
+			err = fmt.Errorf("failed to update state store: %w", err)
+		}
+	}
+	return
+}
+
 // JoinRoomByID joins the client to a room ID. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidjoin
 //
 // Unlike JoinRoom, this method can only be used to join rooms that the server already knows about.
diff --git a/requests.go b/requests.go
index 0ae90d63..377534ae 100644
--- a/requests.go
+++ b/requests.go
@@ -156,6 +156,11 @@ type ReqJoinRoom struct {
 	ThirdPartySigned any      `json:"third_party_signed,omitempty"`
 }
 
+type ReqKnockRoom struct {
+	Via    []string `json:"-"`
+	Reason string   `json:"reason,omitempty"`
+}
+
 type ReqMutualRooms struct {
 	From string `json:"-"`
 }
diff --git a/responses.go b/responses.go
index 04f79143..158d2444 100644
--- a/responses.go
+++ b/responses.go
@@ -33,6 +33,11 @@ type RespJoinRoom struct {
 	RoomID id.RoomID `json:"room_id"`
 }
 
+// RespKnockRoom is the JSON response for https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3knockroomidoralias
+type RespKnockRoom struct {
+	RoomID id.RoomID `json:"room_id"`
+}
+
 // RespLeaveRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidleave
 type RespLeaveRoom struct{}