Scheduling api

[sunbagel]

Notion ticket link

Scheduling API

Implementation description

• Implemented Schemas and APIs for Availability and Suggested Times

First a volunteer defines their availability. This defines time blocks that they are available for, and are reused across all matches.
Upon matching, the participant will receive the volunteer's availability. They have two options:

1. Select one of the available times and use that as the match. If it is available, then the match will use that time.
2. If they don't like the times available, they can suggest their own times. This creates SuggestedTimes. The volunteer will then have to approve one of these suggested times.

TimeBlocks are defined as 30 minute intervals. On creation and deletion, only hourly intervals can be specified.
ex. Creating a TimeBlock from 1:00-2:00pm will create a 1:00pm timeblock and a 1:30pm timeblock.

More details:
https://docs.google.com/document/d/1QYDSE_e6GRQzN06uyrLwHkJ6iZxr30GgwbMxQJNGg4o/edit?tab=t.0

Steps to test

Testing Availability

1. Create a User
2. Create a Schedule:

POST http://localhost:8000/availability
{
    "user_id": "c42beb3c-17c1-4f00-87c9-17caba9bfc2d",
    "available_times": [
        {
            "start_time": "2025-06-15T01:00:00Z",
            "end_time": "2025-06-15T03:00:00Z"
        }
    ]
}

Expected Response the first time:

{
    "user_id": "c42beb3c-17c1-4f00-87c9-17caba9bfc2d",
    "added": 4
}

Expected Response if TimeBlocks already exist for those times + for that user (ex. running the same request a second time)

{
    "user_id": "c42beb3c-17c1-4f00-87c9-17caba9bfc2d",
    "added": 0
}

In the database, you should see the TimeBlocks created in the TimeBlocks table:

And also the Availability created in the availability table, connecting your user id and the time block ids:

3. Get Availability
   http://localhost:8000/availability?user_id=c42beb3c-17c1-4f00-87c9-17caba9bfc2d

• Provide the user id in the query string
• Verify that your availability was created and its at the right times

4. Delete Availability

DELETE http://localhost:8000/availability
{
  "user_id": "c42beb3c-17c1-4f00-87c9-17caba9bfc2d",
  "delete": [
    {
        "start_time": "2025-06-15T01:00:00Z",
        "end_time": "2025-06-15T02:00:00Z"
    }
  ]
}

Deletes 1:00 and 1:30 timeblocks, but not 2:00 and 2:30.

Expected Output:
{
    "user_id": "c42beb3c-17c1-4f00-87c9-17caba9bfc2d",
    "deleted": 2,
    "availability": [
        ...
     ]
}

• Since we only deleted 1:00-2:00, we should expect the timeblocks at 2:00 and 2:30 to still exist, hence the request returns deleted=2. Verify that the correct time blocks were deleted in the returned availability (shows all time blocks).

Error case: If you try to specify an interval that's not hourly (ex. 1pm to 2:30pm)
Can't delete in 30 min intervals, only in hourly intervals. You'll get this error:
{
    "detail": [
        {
            "type": "value_error",
            "loc": [
                "body",
                "delete",
                0
            ],
            "msg": "Value error, Times must be on the hour",
            "input": {
                "start_time": "2025-06-15T01:00:00Z",
                "end_time": "2025-06-16T02:30:00Z"
            },
            "ctx": {
                "error": {}
            }
        }
    ]
}

Testing Suggested Times

TODO - FILL THIS IN

Next Steps:

• A comprehensive Matches API has not been implemented. Further testing will be needed to test it. I created a route that confirms a time but this can't be tested until we have Matches to test it with.
• Furthermore, we also need to update Matches state accordingly when we submit suggested times / confirm times.

What should reviewers focus on?

• Reviewing the flow and schema design (outlined in the Google doc)
• Review service logic, edge cases

Checklist

• My PR name is descriptive and in imperative tense
• My commit messages are descriptive and in imperative tense. My commits are atomic and trivial commits are squashed or fixup'd into non-trivial commits
• I have run the appropriate linter(s)
• I have requested a review from the PL, as well as other devs who have background knowledge on this PR or who will be building on top of this PR