Add response to `ReadRepoNotifications` (#590)

- This is a breaking change.
- Return the relevant notifications when the Gitea server is 1.16.0 or higher.
- Ref: https://github.com/go-gitea/gitea/pull/17064
- Resolves #543

Reviewed-on: https://gitea.com/gitea/go-sdk/pulls/590
Reviewed-by: 6543 <6543@obermui.de>
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: Gusted <williamzijl7@hotmail.com>
Co-committed-by: Gusted <williamzijl7@hotmail.com>

docs/migrate-v0.15-to-v0.16.md

@@ -19,3 +19,10 @@ As we aim to track API changes in Gitea 1.16 with this SDK release, you may find
  Related PRs:
  - [go-sdk#542](https://gitea.com/gitea/go-sdk/pulls/542)
  - [gitea#17158](https://github.com/go-gitea/gitea/pull/17158)
+
+## ReadNotification, ReadNotifications, ReadRepoNotifications
+The function now has a new return argument. The read notifications will now be returned by Gitea 1.16. If you don't require this information, use a blank identifier for the return variable. 
+
+Related PRs:
+ - [go-sdk#590](https://gitea.com/gitea/go-sdk/pulls/590)
+ - [gitea#17064](https://github.com/go-gitea/gitea/pull/17064)

gitea/notifications.go

@@ -160,16 +160,22 @@ func (c *Client) GetNotification(id int64) (*NotificationThread, *Response, erro
 
 // ReadNotification mark notification thread as read by ID
 // It optionally takes a second argument if status has to be set other than 'read'
-func (c *Client) ReadNotification(id int64, status ...NotifyStatus) (*Response, error) {
+// The relevant notification will be returned as the first parameter when the Gitea server is 1.16.0 or higher.
+func (c *Client) ReadNotification(id int64, status ...NotifyStatus) (*NotificationThread, *Response, error) {
 	if err := c.checkServerVersionGreaterThanOrEqual(version1_12_0); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	link := fmt.Sprintf("/notifications/threads/%d", id)
 	if len(status) != 0 {
 		link += fmt.Sprintf("?to-status=%s", status[0])
 	}
+	if err := c.checkServerVersionGreaterThanOrEqual(version1_16_0); err == nil {
+		thread := &NotificationThread{}
+		resp, err := c.getParsedResponse("PATCH", link, nil, nil, thread)
+		return thread, resp, err
+	}
 	_, resp, err := c.getResponse("PATCH", link, nil, nil)
-	return resp, err
+	return nil, resp, err
 }
 
 // ListNotifications list users's notification threads
@@ -188,17 +194,24 @@ func (c *Client) ListNotifications(opt ListNotificationOptions) ([]*Notification
 }
 
 // ReadNotifications mark notification threads as read
-func (c *Client) ReadNotifications(opt MarkNotificationOptions) (*Response, error) {
+// The relevant notifications will only be returned as the first parameter when the Gitea server is 1.16.0 or higher.
+func (c *Client) ReadNotifications(opt MarkNotificationOptions) ([]*NotificationThread, *Response, error) {
 	if err := c.checkServerVersionGreaterThanOrEqual(version1_12_0); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	if err := opt.Validate(c); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	link, _ := url.Parse("/notifications")
 	link.RawQuery = opt.QueryEncode()
+
+	if err := c.checkServerVersionGreaterThanOrEqual(version1_16_0); err == nil {
+		threads := make([]*NotificationThread, 0, 10)
+		resp, err := c.getParsedResponse("PUT", link.String(), nil, nil, &threads)
+		return threads, resp, err
+	}
 	_, resp, err := c.getResponse("PUT", link.String(), nil, nil)
-	return resp, err
+	return nil, resp, err
 }
 
 // ListRepoNotifications list users's notification threads on a specific repo
@@ -220,18 +233,25 @@ func (c *Client) ListRepoNotifications(owner, repo string, opt ListNotificationO
 }
 
 // ReadRepoNotifications mark notification threads as read on a specific repo
-func (c *Client) ReadRepoNotifications(owner, repo string, opt MarkNotificationOptions) (*Response, error) {
+// The relevant notifications will only be returned as the first parameter when the Gitea server is 1.16.0 or higher.
+func (c *Client) ReadRepoNotifications(owner, repo string, opt MarkNotificationOptions) ([]*NotificationThread, *Response, error) {
 	if err := escapeValidatePathSegments(&owner, &repo); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	if err := c.checkServerVersionGreaterThanOrEqual(version1_12_0); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	if err := opt.Validate(c); err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	link, _ := url.Parse(fmt.Sprintf("/repos/%s/%s/notifications", owner, repo))
 	link.RawQuery = opt.QueryEncode()
+
+	if err := c.checkServerVersionGreaterThanOrEqual(version1_16_0); err == nil {
+		threads := make([]*NotificationThread, 0, 10)
+		resp, err := c.getParsedResponse("PUT", link.String(), nil, nil, &threads)
+		return threads, resp, err
+	}
 	_, resp, err := c.getResponse("PUT", link.String(), nil, nil)
-	return resp, err
+	return nil, resp, err
 }

gitea/notifications_test.go

@@ -35,8 +35,9 @@ func TestNotifications(t *testing.T) {
 	assert.NoError(t, err)
 
 	c.sudo = user2.UserName
-	_, err = c.ReadNotifications(MarkNotificationOptions{})
+	notifications, _, err := c.ReadNotifications(MarkNotificationOptions{})
 	assert.NoError(t, err)
+	assert.Len(t, notifications, 0)
 	count, _, err := c.CheckNotifications()
 	assert.EqualValues(t, 0, count)
 	assert.NoError(t, err)
@@ -77,8 +78,9 @@ func TestNotifications(t *testing.T) {
 	assert.Len(t, nList, 1)
 	assert.EqualValues(t, "A Issue", nList[0].Subject.Title)
 	// ReadRepoNotifications
-	_, err = c.ReadRepoNotifications(repoA.Owner.UserName, repoA.Name, MarkNotificationOptions{})
+	notifications, _, err = c.ReadRepoNotifications(repoA.Owner.UserName, repoA.Name, MarkNotificationOptions{})
 	assert.NoError(t, err)
+	assert.Len(t, notifications, 1)
 
 	// GetThread
 	n, _, err := c.GetNotification(nList[0].ID)
@@ -87,8 +89,9 @@ func TestNotifications(t *testing.T) {
 	assert.EqualValues(t, "A Issue", n.Subject.Title)
 
 	// ReadNotifications
-	_, err = c.ReadNotifications(MarkNotificationOptions{})
+	notifications, _, err = c.ReadNotifications(MarkNotificationOptions{})
 	assert.NoError(t, err)
+	assert.Len(t, notifications, 1)
 	nList, _, err = c.ListNotifications(ListNotificationOptions{})
 	assert.NoError(t, err)
 	assert.Len(t, nList, 0)
@@ -108,21 +111,26 @@ func TestNotifications(t *testing.T) {
 	assert.EqualValues(t, 1, count)
 	if assert.Len(t, nList, 1) {
 		assert.EqualValues(t, NotifySubjectClosed, nList[0].Subject.State)
-		_, err = c.ReadNotification(nList[0].ID)
+		notification, _, err := c.ReadNotification(nList[0].ID)
 		assert.NoError(t, err)
+		assert.EqualValues(t, notification.ID, nList[0].ID)
 	}
 
 	c.sudo = ""
-	_, err = c.ReadNotifications(MarkNotificationOptions{})
+	notifications, _, err = c.ReadNotifications(MarkNotificationOptions{})
 	assert.NoError(t, err)
+	assert.Len(t, notifications, 2)
 	_, _ = c.DeleteRepo("test01", "Reviews")
 	nList, _, err = c.ListNotifications(ListNotificationOptions{Status: []NotifyStatus{NotifyStatusRead}})
 	assert.NoError(t, err)
 	assert.Len(t, nList, 2)
 
-	_, err = c.ReadNotification(nList[0].ID, NotifyStatusPinned)
+	notification, _, err := c.ReadNotification(nList[0].ID, NotifyStatusPinned)
+	assert.EqualValues(t, notification.ID, nList[0].ID)
 	assert.NoError(t, err)
-	_, err = c.ReadNotification(nList[1].ID, NotifyStatusUnread)
+
+	notification, _, err = c.ReadNotification(nList[1].ID, NotifyStatusUnread)
+	assert.EqualValues(t, notification.ID, nList[1].ID)
 	assert.NoError(t, err)
 	nList, _, err = c.ListNotifications(ListNotificationOptions{Status: []NotifyStatus{NotifyStatusPinned, NotifyStatusUnread}})
 	assert.NoError(t, err)