Merge pull request #262 from pierce-m/ticket-comment-list-pagination

Add cursor pagination for list ticket comments.

Author: nukosuke

fixture/GET/ticket_comments.json

@@ -22,5 +22,10 @@
 		  "attachments": [],
 		  "created_at": "2019-06-03T02:23:47Z"
 	  }
-  ]
+  ],
+  "meta": {
+    "has_more": true,
+    "after_cursor": "xxx",
+    "before_cursor": "yyy"
+  }
 }

zendesk/cursor.go

@@ -1,5 +1,8 @@
 package zendesk
 
+// DEPRECATED -- This file describes Zendesk API's "legacy" cursor pagination.
+// PLEASE USE CursorPagination IN zendesk.go INSTEAD!
+
 // Cursor is struct for cursor-based pagination
 type Cursor struct {
 	AfterURL     string `json:"after_url"`

zendesk/mock/client.go

@@ -10,7 +10,7 @@ import (
 // TicketCommentAPI is an interface containing all ticket comment related API methods
 type TicketCommentAPI interface {
 	CreateTicketComment(ctx context.Context, ticketID int64, ticketComment TicketComment) (TicketComment, error)
-	ListTicketComments(ctx context.Context, ticketID int64) ([]TicketComment, error)
+	ListTicketComments(ctx context.Context, ticketID int64, opts *ListTicketCommentsOptions) (*ListTicketCommentsResult, error)
 	MakeCommentPrivate(ctx context.Context, ticketID int64, ticketCommentID int64) error
 }
 
@@ -89,25 +89,65 @@ func (z *Client) CreateTicketComment(ctx context.Context, ticketID int64, ticket
 	return result, err
 }
 
+type listTicketCommentsSort string
+
+const (
+	// TicketCommentCreatedAtAsc defines ASC sort val.
+	TicketCommentCreatedAtAsc listTicketCommentsSort = "created_at"
+
+	// TicketCommentCreatedAtDesc defines DESC sort val.
+	TicketCommentCreatedAtDesc listTicketCommentsSort = "-created_at"
+
+	// ListTicketCommentsMaxPageSize contains the max page size.
+	ListTicketCommentsMaxPageSize int = 100
+)
+
+// ListTicketCommentOptions contains all the options supported by ListTicketComments endpoint.
+type ListTicketCommentsOptions struct {
+	CursorPagination
+
+	Include             string                 `url:"include,omitempty"`
+	IncludeInlineImages string                 `url:"include_inline_images,omitempty"`
+	Sort                listTicketCommentsSort `url:"sort,omitempty"`
+}
+
+// ListTicketCommentsResult contains the resulting ticket comments
+// and cursor pagination metadata.
+type ListTicketCommentsResult struct {
+	TicketComments []TicketComment      `json:"comments"`
+	Meta           CursorPaginationMeta `json:"meta"`
+}
+
 // ListTicketComments gets a list of comment for a specified ticket
 //
 // ref: https://developer.zendesk.com/rest_api/docs/support/ticket_comments#list-comments
-func (z *Client) ListTicketComments(ctx context.Context, ticketID int64) ([]TicketComment, error) {
-	var result struct {
-		TicketComments []TicketComment `json:"comments"`
+func (z *Client) ListTicketComments(
+	ctx context.Context,
+	ticketID int64,
+	opts *ListTicketCommentsOptions,
+) (*ListTicketCommentsResult, error) {
+	url := fmt.Sprintf("/tickets/%d/comments.json", ticketID)
+
+	var err error
+	if opts != nil {
+		url, err = addOptions(url, opts)
+		if err != nil {
+			return nil, err
+		}
 	}
 
-	body, err := z.get(ctx, fmt.Sprintf("/tickets/%d/comments.json", ticketID))
+	body, err := z.get(ctx, url)
 	if err != nil {
-		return []TicketComment{}, err
+		return nil, err
 	}
 
+	var result ListTicketCommentsResult
 	err = json.Unmarshal(body, &result)
 	if err != nil {
-		return []TicketComment{}, err
+		return nil, err
 	}
 
-	return result.TicketComments, err
+	return &result, err
 }
 
 // MakeCommentPrivate converts an existing ticket comment to an internal note that is not publicly viewable.

zendesk/ticket_comment.go

@@ -43,14 +43,26 @@ func TestListTicketComments(t *testing.T) {
 	client := newTestClient(mockAPI)
 	defer mockAPI.Close()
 
-	ticketComments, err := client.ListTicketComments(ctx, 2)
+	result, err := client.ListTicketComments(ctx, 2, nil)
 	if err != nil {
 		t.Fatalf("Failed to list ticket comments: %s", err)
 	}
 
 	expectedLength := 2
-	if len(ticketComments) != expectedLength {
-		t.Fatalf("Returned ticket comments does not have the expected length %d. Ticket comments length is %d", expectedLength, len(ticketComments))
+	if len(result.TicketComments) != expectedLength {
+		t.Fatalf("Returned ticket comments does not have the expected length %d. Ticket comments length is %d", expectedLength, len(result.TicketComments))
+	}
+
+	expectedPaginationMeta := CursorPaginationMeta{
+		HasMore:      true,
+		AfterCursor:  "xxx",
+		BeforeCursor: "yyy",
+	}
+
+	if result.Meta != expectedPaginationMeta {
+		t.Fatalf(`Failed to return correct cursor options.
+Expected: %+v
+Received: %+v`, expectedPaginationMeta, result.Meta)
 	}
 }
 

zendesk/ticket_comment_test.go

@@ -40,6 +40,33 @@ type (
 		Put(ctx context.Context, path string, data interface{}) ([]byte, error)
 		Delete(ctx context.Context, path string) error
 	}
+
+	// CursorPagination contains options for using cursor pagination.
+	// Cursor pagination is preferred where possible.
+	CursorPagination struct {
+		// PageSize sets the number of results per page.
+		// Most endpoints support up to 100 records per page.
+		PageSize int `url:"page[size],omitempty"`
+
+		// PageAfter provides the "next" cursor.
+		PageAfter string `url:"page[after],omitempty"`
+
+		// PageBefore provides the "previous" cursor.
+		PageBefore string `url:"page[before],omitempty"`
+	}
+
+	// CursorPaginationMeta contains information concerning how to fetch
+	// next and previous results, and if next results exist.
+	CursorPaginationMeta struct {
+		// HasMore is true if more results exist in the endpoint.
+		HasMore bool `json:"has_more,omitempty"`
+
+		// AfterCursor contains the cursor of the next result set.
+		AfterCursor string `json:"after_cursor,omitempty"`
+
+		// BeforeCursor contains the cursor of the previous result set.
+		BeforeCursor string `json:"before_cursor,omitempty"`
+	}
 )
 
 // NewClient creates new Zendesk API client