feat: add support for listing import events via events.listImportEvents() (#266)

# Background
Adding support for the `GET /v3/grants/{grant_id}/events/import`
endpoint
(https://developer.nylas.com/docs/api/v3/ecc/#get-/v3/grants/-grant_id-/events/import)

# License
<!-- Your PR comment must contain the following line for us to merge the
PR. -->
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.

Author: AaronDDM

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Nylas Java SDK Changelog
 
+### [Unreleased]
+* Added support for listing import events via `events.listImportEvents()`
+
 ### [2.6.0] - Released 2025-01-24
 * Made `NylasClient` and its methods open to enable mocking in tests
 * Added pagination support for folders

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

@@ -0,0 +1,117 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of the query parameters for listing import events.
+ */
+data class ListImportEventQueryParams(
+  /**
+   * Filter for the specified calendar ID.
+   * (Not supported for iCloud) You can use primary to query the end user's primary calendar.
+   * This is a required parameter.
+   */
+  @Json(name = "calendar_id")
+  val calendarId: String,
+  /**
+   * The maximum number of objects to return.
+   * This field defaults to 50. The maximum allowed value is 500.
+   */
+  @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,
+  /**
+   * Filter for events that start at or after the specified time, in Unix timestamp format.
+   * Defaults to the time that you make the request.
+   */
+  @Json(name = "start")
+  val start: Int? = null,
+  /**
+   * Filter for events that end at or before the specified time, in Unix timestamp format.
+   * Defaults to one month from the time you make the request.
+   */
+  @Json(name = "end")
+  val end: Int? = null,
+  /**
+   * Specify fields that you want Nylas to return, as a comma-separated list.
+   * This allows you to receive only the portion of object data that you're interested in.
+   */
+  @Json(name = "select")
+  val select: String? = null,
+) : IQueryParams {
+  /**
+   * Builder for [ListImportEventQueryParams].
+   */
+  data class Builder(
+    /**
+     * Filter for the specified calendar ID.
+     * (Not supported for iCloud) You can use primary to query the end user's primary calendar.
+     * This is a required parameter.
+     */
+    private val calendarId: String,
+  ) {
+    private var limit: Int? = null
+    private var pageToken: String? = null
+    private var start: Int? = null
+    private var end: Int? = null
+    private var select: String? = null
+
+    /**
+     * Sets the maximum number of objects to return.
+     * This field defaults to 50. The maximum allowed value is 500.
+     * @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 [ListResponse.nextCursor] 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 start time to filter events by.
+     * Filter for events that start at or after the specified time, in Unix timestamp format.
+     * @param start The start time to filter events by.
+     * @return The builder.
+     */
+    fun start(start: Int?) = apply { this.start = start }
+
+    /**
+     * Sets the end time to filter events by.
+     * Filter for events that end at or before the specified time, in Unix timestamp format.
+     * @param end The end time to filter events by.
+     * @return The builder.
+     */
+    fun end(end: Int?) = apply { this.end = end }
+
+    /**
+     * Sets the fields to return in the response.
+     * Specify fields that you want Nylas to return, as a comma-separated list.
+     * @param select The fields to return in the response.
+     * @return The builder.
+     */
+    fun select(select: String?) = apply { this.select = select }
+
+    /**
+     * Builds a [ListImportEventQueryParams] instance.
+     * @return The [ListImportEventQueryParams] instance.
+     */
+    fun build() = ListImportEventQueryParams(
+      calendarId,
+      limit,
+      pageToken,
+      start,
+      end,
+      select,
+    )
+  }
+}

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

@@ -26,6 +26,23 @@ class Events(client: NylasClient) : Resource<Event>(client, Event::class.java) {
     return listResource(path, queryParams, overrides)
   }
 
+  /**
+   * Returns a list of recurring events, recurring event exceptions,
+   * and single events from the specified calendar within a given time frame.
+   * This is useful when you want to import, store, and synchronize events
+   * from the time frame to your application
+   * @param identifier Grant ID or email account to query
+   * @param queryParams The query parameters to include in the request (must include calendar_id)
+   * @param overrides Optional request overrides to apply
+   * @return The list of import events
+   */
+  @Throws(NylasApiError::class, NylasSdkTimeoutError::class)
+  @JvmOverloads
+  fun listImportEvents(identifier: String, queryParams: ListImportEventQueryParams, overrides: RequestOverrides? = null): ListResponse<Event> {
+    val path = String.format("v3/grants/%s/events/import", identifier)
+    return listResource(path, queryParams, overrides)
+  }
+
   /**
    * Return an Event
    * @param identifier Grant ID or email account to query

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

@@ -245,6 +245,35 @@ class EventsTests {
       assertEquals(Types.newParameterizedType(ListResponse::class.java, Event::class.java), typeCaptor.firstValue)
     }
 
+    @Test
+    fun `listing import events calls requests with the correct params`() {
+      val listImportEventQueryParams =
+        ListImportEventQueryParams.Builder("calendar-id")
+          .limit(50)
+          .pageToken("next-page-token")
+          .start(1620000000)
+          .end(1620100000)
+          .select("id,title,when")
+          .build()
+
+      events.listImportEvents(grantId, listImportEventQueryParams)
+
+      val pathCaptor = argumentCaptor<String>()
+      val typeCaptor = argumentCaptor<Type>()
+      val queryParamCaptor = argumentCaptor<ListImportEventQueryParams>()
+      val overrideParamCaptor = argumentCaptor<RequestOverrides>()
+      verify(mockNylasClient).executeGet<ListResponse<Event>>(
+        pathCaptor.capture(),
+        typeCaptor.capture(),
+        queryParamCaptor.capture(),
+        overrideParamCaptor.capture(),
+      )
+
+      assertEquals("v3/grants/$grantId/events/import", pathCaptor.firstValue)
+      assertEquals(Types.newParameterizedType(ListResponse::class.java, Event::class.java), typeCaptor.firstValue)
+      assertEquals(listImportEventQueryParams, queryParamCaptor.firstValue)
+    }
+
     @Test
     fun `finding a event calls requests with the correct params`() {
       val eventId = "event-123"