Add Free-Busy Support (#163)

# Description
This PR adds support for the free busy endpoint.

# 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.

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Nylas Java SDK Changelog
 
+## [2.0.0-beta.2] - TBD
+
+### Added
+* Added support for the free-busy endpoint
+
 ## [2.0.0-beta.1] - Released 2023-08-16
 
 ### BREAKING CHANGES

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

@@ -0,0 +1,24 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a Nylas free-busy time slot object.
+ */
+data class FreeBusyTimeSlot(
+  /**
+   * Unix timestamp for the start of the slot.
+   */
+  @Json(name = "start_time")
+  val startTime: Int,
+  /**
+   * Unix timestamp for the end of the slot.
+   */
+  @Json(name = "end_time")
+  val endTime: Int,
+  /**
+   * The status of the time slot.
+   */
+  @Json(name = "status")
+  val status: String,
+)

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

@@ -0,0 +1,14 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Enum representing the type of free/busy information returned for a calendar.
+ */
+enum class FreeBusyType(val value: String) {
+  @Json(name = "free_busy")
+  FREE_BUSY("free_busy"),
+
+  @Json(name = "error")
+  ERROR("error"),
+}

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

@@ -0,0 +1,24 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a Nylas get free-busy request
+ */
+data class GetFreeBusyRequest(
+  /**
+   * Unix timestamp representing the start of the time block for assessing the account's free/busy schedule.
+   */
+  @Json(name = "start_time")
+  val startTime: Int,
+  /**
+   * Unix timestamp representing the end of the time block for assessing the account's free/busy schedule.
+   */
+  @Json(name = "end_time")
+  val endTime: Int,
+  /**
+   * A list of email addresses to check the free/busy schedules for.
+   */
+  @Json(name = "emails")
+  val emails: List<String>,
+)

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

@@ -0,0 +1,72 @@
+package com.nylas.models
+
+import com.nylas.util.JsonHelper
+import com.squareup.moshi.Json
+import com.squareup.moshi.JsonAdapter
+import com.squareup.moshi.adapters.PolymorphicJsonAdapterFactory
+
+/**
+ * Class representation of a Nylas get free busy response.
+ * It can be either a [FreeBusy] or a [FreeBusyError].
+ */
+sealed class GetFreeBusyResponse {
+  /**
+   * The type of the response.
+   */
+  @Json(name = "object")
+  protected open val obj: FreeBusyType? = null
+
+  /**
+   * The participant's email address.
+   */
+  @Json(name = "email")
+  abstract val email: String
+
+  /**
+   * This class represents a successful free-busy response.
+   */
+  data class FreeBusy(
+    /**
+     * A list of busy time slots.
+     */
+    @Json(name = "time_slots")
+    val timeSlots: List<FreeBusyTimeSlot>,
+    @Json(name = "object")
+    override val obj: FreeBusyType = FreeBusyType.FREE_BUSY,
+    @Json(name = "email")
+    override val email: String,
+  ) : GetFreeBusyResponse()
+
+  /**
+   * This class represents a failed free-busy response.
+   */
+  data class FreeBusyError(
+    /**
+     * Description of the error fetching data for this participant.
+     */
+    @Json(name = "error")
+    val error: String,
+    @Json(name = "object")
+    override val obj: FreeBusyType = FreeBusyType.ERROR,
+    @Json(name = "email")
+    override val email: String,
+  ) : GetFreeBusyResponse()
+
+  companion object {
+    /**
+     * A JsonAdapter factory for the [GetFreeBusyResponse] sealed class (used for deserialization).
+     * @suppress Not for public use.
+     */
+    @JvmStatic
+    val FREE_BUSY_JSON_FACTORY: JsonAdapter.Factory = PolymorphicJsonAdapterFactory.of(GetFreeBusyResponse::class.java, "object")
+      .withSubtype(FreeBusy::class.java, FreeBusyType.FREE_BUSY.value)
+      .withSubtype(FreeBusyError::class.java, FreeBusyType.ERROR.value)
+
+    /**
+     * A JsonAdapter for the [GetFreeBusyResponse] sealed class (used for serialization).
+     * @suppress Not for public use.
+     */
+    @JvmStatic
+    val GET_FREE_BUSY_RESPONSE_ADAPTER = JsonHelper.listTypeOf(GetFreeBusyResponse::class.java)
+  }
+}

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

@@ -2,7 +2,9 @@ package com.nylas.resources
 
 import com.nylas.NylasClient
 import com.nylas.models.*
+import com.nylas.models.GetFreeBusyResponse.Companion.GET_FREE_BUSY_RESPONSE_ADAPTER
 import com.nylas.util.JsonHelper
+import com.squareup.moshi.Types
 
 /**
  * Nylas Calendar API
@@ -84,6 +86,7 @@ class Calendars(client: NylasClient) : Resource<Calendar>(client, Calendar::clas
    * @param request The availability request
    * @return The availability response
    */
+  @Throws(NylasApiError::class, NylasSdkTimeoutError::class)
   fun getAvailability(request: GetAvailabilityRequest): Response<GetAvailabilityResponse> {
     val path = "v3/calendars/availability"
 
@@ -93,4 +96,23 @@ class Calendars(client: NylasClient) : Resource<Calendar>(client, Calendar::clas
 
     return client.executePost(path, GetAvailabilityResponse::class.java, serializedRequestBody)
   }
+
+  /**
+   * Get the free/busy schedule for a list of email addresses
+   * @param identifier The identifier of the grant to act upon
+   * @param request The free/busy request
+   * @return The free/busy response
+   */
+  @Throws(NylasApiError::class, NylasSdkTimeoutError::class)
+  fun getFreeBusy(identifier: String, request: GetFreeBusyRequest): Response<GetFreeBusyResponse> {
+    val path = String.format("v3/grants/%s/calendars/free-busy", identifier)
+
+    val serializedRequestBody = JsonHelper.moshi()
+      .adapter(GetFreeBusyRequest::class.java)
+      .toJson(request)
+
+    val responseType = Types.newParameterizedType(Response::class.java, GET_FREE_BUSY_RESPONSE_ADAPTER)
+
+    return client.executePost(path, responseType, serializedRequestBody)
+  }
 }

src/main/kotlin/com/nylas/util/JsonHelper.kt

@@ -1,5 +1,6 @@
 package com.nylas.util
 
+import com.nylas.models.GetFreeBusyResponse.Companion.FREE_BUSY_JSON_FACTORY
 import com.nylas.models.When.Companion.WHEN_JSON_FACTORY
 import com.squareup.moshi.JsonAdapter
 import com.squareup.moshi.JsonReader
@@ -29,6 +30,7 @@ class JsonHelper {
       .add(UpdateWhenAdapter())
       // Polymorphic adapters
       .add(WHEN_JSON_FACTORY)
+      .add(FREE_BUSY_JSON_FACTORY)
       .add(KotlinJsonAdapterFactory())
       .build()