Scheduler API Support (#252)

This PR adds support to the scheduler API, this includes managing
configurations, sessions, and bookings.

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

---------

Co-authored-by: Subash Pradhan <subash.p@macbook-pro.home>
Co-authored-by: Aaron de Mello <314152+AaronDDM@users.noreply.github.com>

Author: 3 people

src/main/kotlin/com/nylas/NylasClient.kt

@@ -151,6 +151,12 @@ class NylasClient(
    */
   fun contacts(): Contacts = Contacts(this)
 
+  /**
+   * Access the Scheduler API
+   * @return The Scheduler API
+   */
+  fun scheduler(): Scheduler = Scheduler(this)
+
   /**
    * Get a URL builder instance for the Nylas API.
    */

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

@@ -11,4 +11,7 @@ enum class AvailabilityMethod {
 
   @Json(name = "max-availability")
   MAX_AVAILABILITY,
+
+  @Json(name = "collective")
+  COLLECTIVE,
 }

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

@@ -14,7 +14,7 @@ data class AvailabilityRules(
   /**
    * The buffer to add to the start and end of a meeting.
    */
-  @Json(name = "meeting_buffer")
+  @Json(name = "buffer")
   val buffer: MeetingBuffer? = null,
   /**
    * A default set of open hours to apply to all participants.
@@ -27,8 +27,8 @@ data class AvailabilityRules(
    * The ID on events that Nylas considers when calculating the order of round-robin participants.
    * This is used for both max-fairness and max-availability methods.
    */
-  @Json(name = "round_robin_event_id")
-  val roundRobinEventId: String? = null,
+  @Json(name = "round_robin_group_id")
+  val roundRobinGroupId: String? = null,
 ) {
   /**
    * A builder for creating a [AvailabilityRules].
@@ -37,7 +37,7 @@ data class AvailabilityRules(
     private var availabilityMethod: AvailabilityMethod? = null
     private var buffer: MeetingBuffer? = null
     private var defaultOpenHours: List<OpenHours>? = null
-    private var roundRobinEventId: String? = null
+    private var roundRobinGroupId: String? = null
 
     /**
      * Set the method used to determine availability for a meeting.
@@ -65,10 +65,10 @@ data class AvailabilityRules(
     /**
      * Set the ID on events that Nylas considers when calculating the order of round-robin participants.
      * This is used for both max-fairness and max-availability methods.
-     * @param roundRobinEventId The ID on events that Nylas considers when calculating the order of round-robin participants.
+     * @param roundRobinGroupId The ID on events that Nylas considers when calculating the order of round-robin participants.
      * @return The builder.
      */
-    fun roundRobinEventId(roundRobinEventId: String) = apply { this.roundRobinEventId = roundRobinEventId }
+    fun roundRobinGroupId(roundRobinGroupId: String) = apply { this.roundRobinGroupId = roundRobinGroupId }
 
     /**
      * Build the [AvailabilityRules] object.
@@ -78,7 +78,7 @@ data class AvailabilityRules(
       availabilityMethod = availabilityMethod,
       buffer = buffer,
       defaultOpenHours = defaultOpenHours,
-      roundRobinEventId = roundRobinEventId,
+      roundRobinGroupId = roundRobinGroupId,
     )
   }
 }

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

@@ -0,0 +1,19 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a booking guest.
+ */
+data class BookingGuest(
+  /**
+   * The email address of the guest.
+   */
+  @Json(name = "email")
+  val email: String,
+  /**
+   * The name of the guest.
+   */
+  @Json(name = "name")
+  val name: String? = null,
+)

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

@@ -0,0 +1,19 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a booking organizer.
+ */
+data class BookingOrganizer(
+  /**
+   * The email address of the participant designated as the organizer of the event.
+   */
+  @Json(name = "email")
+  val email: String,
+  /**
+   * The name of the participant designated as the organizer of the event.
+   */
+  @Json(name = "name")
+  val name: String? = null,
+)

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

@@ -0,0 +1,29 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a booking reminder.
+ */
+data class BookingReminder(
+  /**
+   * The reminder type.
+   */
+  @Json(name = "type")
+  val type: String,
+  /**
+   * The number of minutes before the event to send the reminder.
+   */
+  @Json(name = "minutes_before_event")
+  val minutesBeforeEvent: Int,
+  /**
+   * The recipient of the reminder.
+   */
+  @Json(name = "recipient")
+  val recipient: String? = null,
+  /**
+   * The subject of the email reminder.
+   */
+  @Json(name = "email_subject")
+  val emailSubject: String? = null,
+)

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

@@ -0,0 +1,17 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Enum for booking statuses.
+ */
+enum class BookingStatus {
+  @Json(name = "pending")
+  PENDING,
+
+  @Json(name = "booked")
+  BOOKED,
+
+  @Json(name = "cancelled")
+  CANCELLED,
+}

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

@@ -0,0 +1,14 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Enum for booking types.
+ */
+enum class BookingType {
+  @Json(name = "booking")
+  BOOKING,
+
+  @Json(name = "organizer-confirmation")
+  ORGANIZER_CONFIRMATION,
+}

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

@@ -0,0 +1,75 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of availability settings.
+ */
+data class ConfigurationAvailability(
+  /**
+   * The total number of minutes the event should last.
+   */
+  @Json(name = "duration_minutes")
+  val durationMinutes: Int? = null,
+  /**
+   * The interval between meetings in minutes.
+   */
+  @Json(name = "interval_minutes")
+  val intervalMinutes: Int? = null,
+  /**
+   * Nylas rounds each time slot to the nearest multiple of this number of minutes.
+   */
+  @Json(name = "round_to")
+  val roundTo: Int? = null,
+  /**
+   * Availability rules for scheduling configuration.
+   */
+  @Json(name = "availability_rules")
+  val availabilityRules: AvailabilityRules? = null,
+) {
+  class Builder {
+    private var durationMinutes: Int? = null
+    private var intervalMinutes: Int? = null
+    private var roundTo: Int? = null
+    private var availabilityRules: AvailabilityRules? = null
+
+    /**
+     * Set the duration of the event in minutes.
+     * @param durationMinutes The duration of the event in minutes.
+     * @return The builder.
+     */
+    fun durationMinutes(durationMinutes: Int?) = apply { this.durationMinutes = durationMinutes }
+
+    /**
+     * Set the interval between meetings in minutes.
+     * @param intervalMinutes The interval between meetings in minutes.
+     * @return The builder.
+     */
+    fun intervalMinutes(intervalMinutes: Int?) = apply { this.intervalMinutes = intervalMinutes }
+
+    /**
+     * Set Nylas rounds each time slot to the nearest multiple of this number of minutes.
+     * @param roundTo Nylas rounds each time slot to the nearest multiple of this number of minutes.
+     * @return The builder.
+     */
+    fun roundTo(roundTo: Int?) = apply { this.roundTo = roundTo }
+
+    /**
+     * Set availability rules for scheduling configuration.
+     * @param availabilityRules Availability rules for scheduling configuration.
+     * @return The builder.
+     */
+    fun availabilityRules(availabilityRules: AvailabilityRules?) = apply { this.availabilityRules = availabilityRules }
+
+    /**
+     * Build the [ConfigurationAvailability].
+     * @return The [ConfigurationAvailability].
+     */
+    fun build() = ConfigurationAvailability(
+      durationMinutes,
+      intervalMinutes,
+      roundTo,
+      availabilityRules,
+    )
+  }
+}

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

@@ -0,0 +1,52 @@
+package com.nylas.models
+
+import com.squareup.moshi.Json
+
+/**
+ * Class representation of a participant in a booking.
+ */
+
+data class ConfigurationAvailabilityParticipant(
+  /**
+   * @param calendarIds The calendar IDs that the event is created in.
+   */
+  @Json(name = "calendar_ids")
+  val calendarIds: List<String>? = emptyList(),
+  /**
+   * Open hours for this participant. The endpoint searches for free time slots during these open hours.
+   */
+  @Json(name = "open_hours")
+  val openHours: List<OpenHours>? = null,
+) {
+  /**
+   * Builder for [ConfigurationAvailabilityParticipant].
+   */
+  class Builder {
+    private var calendarIds: List<String>? = null
+    private var openHours: List<OpenHours>? = null
+
+    /**
+     * Set the calendar IDs for this participant.
+     * @param calendarIds Calendar IDs for this participant.
+     * @return The builder.
+     */
+    fun calendarIds(calendarIds: List<String>) = apply { this.calendarIds = calendarIds }
+
+    /**
+     * Set the open hours for this participant.
+     * @param openHours Open hours for this participant.
+     * @return The builder.
+     */
+    fun openHours(openHours: List<OpenHours>) = apply { this.openHours = openHours }
+
+    /**
+     * Set the open hours for this participant.
+     * @param openHours Open hours for this participant.
+     * @return The builder.
+     */
+    fun build() = ConfigurationAvailabilityParticipant(
+      calendarIds,
+      openHours,
+    )
+  }
+}