Add support for free-busy endpoint (#279)

* Add support for free-busy endpoint

Mostly cribbed off the availability support, though radically stripped
down as free-busy is a great deal simpler.

* debugging

* just work

* fix docs

* fix doc

* rename Error to FreeBusyError

nylas/models/free_busy.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+from typing import List, Union
+
+from dataclasses_json import dataclass_json
+from typing_extensions import TypedDict
+
+
+@dataclass_json
+@dataclass
+class FreeBusyError:
+    """
+    Interface for a Nylas free/busy call error
+
+    Attributes:
+        email: The email address of the participant who had an error.
+        error: The provider's error message.
+    """
+
+    email: str
+    error: str
+
+
+@dataclass_json
+@dataclass
+class TimeSlot:
+    """
+    Interface for a Nylas free/busy time slot
+
+    Attributes:
+        start_time: Unix timestamp for the start of the slot.
+        end_time: Unix timestamp for the end of the slot.
+        status: The status of the slot. Typically "busy"
+    """
+
+    start_time: int
+    end_time: int
+    status: str
+
+
+@dataclass_json
+@dataclass
+class FreeBusy:
+    """
+    Interface for an individual Nylas free/busy response
+
+    Attributes:
+        email: The email address of the participant.
+        time_slots: List of time slots for the participant.
+    """
+
+    email: str
+    time_slots: List[TimeSlot]
+
+
+@dataclass_json
+@dataclass
+class GetFreeBusyResponse:
+    """
+    Interface for a Nylas get free/busy response
+
+    A list of FreeBusy objects and FreeBusyError objects.
+
+    """
+
+    List[Union[FreeBusy, FreeBusyError]]
+
+
+class GetFreeBusyRequest(TypedDict):
+    """
+    Interface for a Nylas get free/busy request
+
+    Attributes:
+        start_time: Unix timestamp for the start time to check free/busy for.
+        end_time: Unix timestamp for the end time to check free/busy for.
+        emails: List of email addresses to check free/busy for.
+    """
+
+    start_time: int
+    end_time: int
+    emails: List[str]

nylas/resources/calendars.py

@@ -6,6 +6,7 @@
     DestroyableApiResource,
 )
 from nylas.models.availability import GetAvailabilityResponse, GetAvailabilityRequest
+from nylas.models.free_busy import GetFreeBusyResponse, GetFreeBusyRequest
 from nylas.models.calendars import (
     Calendar,
     CreateCalendarRequest,
@@ -132,3 +133,24 @@ def get_availability(
         )
 
         return Response.from_dict(json_response, GetAvailabilityResponse)
+
+    def get_free_busy(
+        self, identifier: str, request_body: GetFreeBusyRequest
+    ) -> Response[GetFreeBusyResponse]:
+        """
+        Get free/busy info for a Calendar.
+
+        Args:
+            identifier: The grant ID or email account to get free/busy for.
+            request_body: The request body to send to the API.
+
+        Returns:
+            Response: The free/busy response from the API.
+        """
+        json_response = self._http_client._execute(
+            method="POST",
+            path=f"/v3/grants/{identifier}/calendars/free-busy",
+            request_body=request_body,
+        )
+
+        return Response(json_response, GetFreeBusyResponse)