Update folders: pagination added (#259)

This update addresses a client requirement where the current folder
fetch limit of 50 elements is insufficient due to their large number of
folders. The changes include:

- Adding the pagination system like the others entities

This enhancement improves usability for clients with extensive folder
structures, enabling them to efficiently access and manage their data.

# License
I confirm that this contribution is made under the terms of the MIT
license and that I have the authority necessary to make this
contribution on behalf of its copyright owner.

---------

Co-authored-by: alan <[email protected]>
Co-authored-by: Aaron de Mello <[email protected]>

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Nylas Java SDK Changelog
 
+### Unreleased
+* Added pagination support for folders
+
 ### [2.5.2] - Released 2024-12-02
 * Added support for `skypeForConsumer` as conferencing provider
 

src/main/kotlin/com/nylas/models/ListFoldersQueryParams.kt

@@ -0,0 +1,81 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representing the query parameters for listing messages.
+ */
+data class ListFoldersQueryParams(
+  /**
+   * The maximum number of objects to return.
+   * This field defaults to 50. The maximum allowed value is 200.
+   */
+  @Json(name = "limit")
+  val limit: Int? = null,
+  /**
+   * An identifier that specifies which page of data to return.
+   * This value should be taken from the [ListResponse.nextCursor] response field.
+   */
+  @Json(name = "page_token")
+  val pageToken: String? = null,
+  /**
+   * (Microsoft and EWS only.) Use the ID of a folder to find all child folders it contains.
+   */
+  @Json(name = "parent_id")
+  val parentId: String? = null,
+  /**
+   * Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at).
+   * This allows you to receive only the portion of object data that you're interested in.
+   * You can use select to optimize response size and reduce latency by limiting queries to only the information that you need
+   */
+  @Json(name = "select")
+  var select: String? = null,
+) : IQueryParams {
+  class Builder {
+    private var limit: Int? = null
+    private var pageToken: String? = null
+    private var parentId: String? = null
+    private var select: String? = null
+
+    /**
+     * Sets the maximum number of objects to return.
+     * This field defaults to 10. The maximum allowed value is 200.
+     * @param limit The maximum number of objects to return.
+     * @return The builder.
+     */
+    fun limit(limit: Int?) = apply { this.limit = limit }
+
+    /**
+     * Sets the identifier that specifies which page of data to return.
+     * This value should be taken from the next_cursor response field.
+     * @param pageToken The identifier that specifies which page of data to return.
+     * @return The builder.
+     */
+    fun pageToken(pageToken: String?) = apply { this.pageToken = pageToken }
+
+    /**
+     * Sets the parent id of the folders to return.
+     * @param parentId The parent id of the folder to return.
+     * @return The builder.
+     */
+    fun parentId(parentId: String?) = apply { this.parentId = parentId }
+
+    /**
+     * Sets the fields to return in the response.
+     * @param select List of field names to return (e.g. "id,updated_at")
+     * @return The builder.
+     */
+    fun select(select: String?) = apply { this.select = select }
+
+    /**
+     * Builds the [ListFoldersQueryParams] object.
+     * @return The [ListFoldersQueryParams] object.
+     */
+    fun build() = ListFoldersQueryParams(
+      limit = limit,
+      pageToken = pageToken,
+      parentId = parentId,
+      select = select,
+    )
+  }
+}

src/main/kotlin/com/nylas/resources/Folders.kt

@@ -8,14 +8,15 @@ class Folders(client: NylasClient) : Resource<Folder>(client, Folder::class.java
   /**
    * Return all Folders
    * @param identifier Grant ID or email account to query.
+   * @param queryParams The query parameters to include in the request
    * @param overrides Optional request overrides to apply
    * @return The list of Folders
    */
   @Throws(NylasApiError::class, NylasSdkTimeoutError::class)
   @JvmOverloads
-  fun list(identifier: String, overrides: RequestOverrides? = null): ListResponse<Folder> {
+  fun list(identifier: String, queryParams: ListFoldersQueryParams? = null, overrides: RequestOverrides? = null): ListResponse<Folder> {
     val path = String.format("v3/grants/%s/folders", identifier)
-    return listResource(path, overrides = overrides)
+    return listResource(path, queryParams, overrides)
   }
 
   /**

src/test/kotlin/com/nylas/resources/FoldersTests.kt

@@ -92,7 +92,14 @@ class FoldersTests {
 
     @Test
     fun `listing folders calls requests with the correct params`() {
-      folders.list(grantId)
+      val queryParams =
+        ListFoldersQueryParams(
+          limit = 10,
+          pageToken = "abc-123",
+          select = "id,updated_at",
+        )
+
+      folders.list(grantId, queryParams)
 
       val pathCaptor = argumentCaptor<String>()
       val typeCaptor = argumentCaptor<Type>()
@@ -107,7 +114,7 @@ class FoldersTests {
 
       assertEquals("v3/grants/$grantId/folders", pathCaptor.firstValue)
       assertEquals(Types.newParameterizedType(ListResponse::class.java, Folder::class.java), typeCaptor.firstValue)
-      assertNull(queryParamCaptor.firstValue)
+      assertEquals(queryParams, queryParamCaptor.firstValue)
     }
 
     @Test