TW-4624: Add specific_time_availability to AvailabilityParticipant

Add support for specific_time_availability field in the /calendars/availability
POST API. This allows overriding open_hours for specific dates.

Changes:
- Added SpecificTimeAvailability TypedDict with date, start, and end fields
- Added specific_time_availability field to AvailabilityParticipant
- Updated and added unit tests for availability endpoint

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: pengfeiye

nylas/models/availability.py

@@ -77,6 +77,22 @@ class OpenHours(TypedDict):
     exdates: NotRequired[List[str]]
 
 
+class SpecificTimeAvailability(TypedDict):
+    """
+    Interface of a participant's availability for specific dates.
+    Overrides open_hours for the specified dates.
+
+    Attributes:
+        dates: The date in ISO 8601 format.
+        start: Start time in 24-hour time format. Leading 0's are left off.
+        end: End time in 24-hour time format. Leading 0's are left off.
+    """
+
+    date: str
+    start: str
+    end: str
+
+
 class AvailabilityRules(TypedDict):
     """
     Interface for the availability rules for a Nylas calendar.
@@ -111,11 +127,14 @@ class AvailabilityParticipant(TypedDict):
         calendar_ids: An optional list of the calendar IDs associated with each participant's email address.
             If not provided, Nylas uses the primary calendar ID.
         open_hours: Open hours for this participant. The endpoint searches for free time slots during these open hours.
+        specific_time_availability: Specific availability for this participant that overrides open_hours
+            for the specified dates.
     """
 
     email: str
     calendar_ids: NotRequired[List[str]]
     open_hours: NotRequired[List[OpenHours]]
+    specific_time_availability: NotRequired[List[SpecificTimeAvailability]]
 
 
 class GetAvailabilityRequest(TypedDict):

tests/resources/test_calendars.py

@@ -320,31 +320,23 @@ def test_get_availability(self, http_client_response):
         request_body = {
             "start_time": 1497916800,
             "end_time": 1498003200,
-            "duration_minutes": 30,
+            "duration_minutes": 60,
             "interval_minutes": 30,
-            "free_busy": [
+            "round_to_30_minutes": True,
+            "participants": [
                 {
                     "email": "test@gmail.com",
-                }
-            ],
-            "open_hours": [
-                {
-                    "days": ["monday", "wednesday"],
-                    "timezone": "America/New_York",
-                    "start": "08:00",
-                    "end": "18:00",
-                    "restrictions": [
+                    "calendar_ids": ["primary"],
+                    "open_hours": [
                         {
-                            "days": ["monday"],
-                            "start": "12:00",
-                            "end": "13:00",
+                            "days": [1, 3],
+                            "timezone": "America/New_York",
+                            "start": "08:00",
+                            "end": "18:00",
                         }
                     ],
                 }
             ],
-            "duration_minutes": 60,
-            "interval_minutes": 30,
-            "round_to_30_minutes": True,
             "availability_rules": {
                 "availability_method": "max-availability",
                 "buffer": {"before": 10, "after": 10},
@@ -362,7 +354,56 @@ def test_get_availability(self, http_client_response):
             },
         }
 
-        calendars.get_availability(request_body,overrides=None,)
+        calendars.get_availability(request_body, overrides=None)
+
+        http_client_response._execute.assert_called_once_with(
+            "POST",
+            "/v3/calendars/availability",
+            None,
+            None,
+            request_body,
+            overrides=None,
+        )
+
+    def test_get_availability_with_specific_time_availability(self, http_client_response):
+        calendars = Calendars(http_client_response)
+        request_body = {
+            "start_time": 1497916800,
+            "end_time": 1498003200,
+            "duration_minutes": 60,
+            "interval_minutes": 30,
+            "participants": [
+                {
+                    "email": "test@gmail.com",
+                    "calendar_ids": ["primary"],
+                    "open_hours": [
+                        {
+                            "days": [1, 2, 3, 4, 5],
+                            "timezone": "America/New_York",
+                            "start": "9:00",
+                            "end": "17:00",
+                        }
+                    ],
+                    "specific_time_availability": [
+                        {
+                            "date": "2024-03-15",
+                            "start": "10:00",
+                            "end": "14:00",
+                        },
+                        {
+                            "date": "2024-03-16",
+                            "start": "10:00",
+                            "end": "14:00",
+                        }
+                    ],
+                }
+            ],
+            "availability_rules": {
+                "availability_method": "max-availability",
+            },
+        }
+
+        calendars.get_availability(request_body, overrides=None)
 
         http_client_response._execute.assert_called_once_with(
             "POST",