diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d7522c1..4c32efcb 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/src/main/kotlin/com/nylas/models/ListImportEventQueryParams.kt b/src/main/kotlin/com/nylas/models/ListImportEventQueryParams.kt new file mode 100644 index 00000000..47e514db --- /dev/null +++ b/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, + ) + } +} diff --git a/src/main/kotlin/com/nylas/resources/Events.kt b/src/main/kotlin/com/nylas/resources/Events.kt index 43f8ef41..cb2037a3 100644 --- a/src/main/kotlin/com/nylas/resources/Events.kt +++ b/src/main/kotlin/com/nylas/resources/Events.kt @@ -26,6 +26,23 @@ class Events(client: NylasClient) : Resource(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 { + 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 diff --git a/src/test/kotlin/com/nylas/resources/EventsTests.kt b/src/test/kotlin/com/nylas/resources/EventsTests.kt index 917f031d..2c248258 100644 --- a/src/test/kotlin/com/nylas/resources/EventsTests.kt +++ b/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() + val typeCaptor = argumentCaptor() + val queryParamCaptor = argumentCaptor() + val overrideParamCaptor = argumentCaptor() + verify(mockNylasClient).executeGet>( + 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"