3. APIs and Controller - leeteresamaria/RoomieMatter GitHub Wiki
Firebase Backend Functions
RoomieMatter's backend is built with Firebase Functions. Firebase functions can only be called from an app registered with Firebase because every Firebase function expects a Firebase authentication token (different than a Google oAuth token).
These functions fall into one of the following categories:
- Chat API (includes interactions with OpenAI API) (source code)
- Calendar API (includes interactions with Google Calendar API) (source code)
- Room API (source code)
- Status API (source code)
Chat API
The Chat API is responsible for handling what happens after the user sends a chat or gets the chat history
Send Chat
Function Identifier: sendChat
The Send Chat Firebase function is called when a user sends a chat. It has the following logical structure:
- Insert the user's chat into Firestore
- If the user's chat does NOT contain @housekeeper, this function exits. Otherwise, it calls OpenAI API with the user's message and a list of functions that can be triggered by the user via GPT. The functions that can be called are defined here. They contain information about how GPT should respond and what action to trigger upon that response.
- Parse OpenAI's response and store it in Firestore. It will tell us what function its calling (or no function) with some parameters.
- Trigger the appropriate function (or trigger no function) and store the result in Firestore.
- If no function was called, exit. Otherwise, send the result to OpenAI API again to summarize it. Insert that response into Firestore as a chat.
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
userId |
Firebase Document Id | The userId of the sender | Required |
roomId |
Firebase Document Id | The room the user is sending a message to | Required |
content |
String | The content of the message | Required |
token |
Google oAuth token | Used to trigger Google Calendar API | Required |
Returns
An object stating whether the operation was successful or not with an error or success code.
Example success response: {success: true, message: "NO_GPT_CALL"}
| Success Code | Description |
|---|---|
NO_GPT_CALL |
The chat didn't contain @housekeeper, so it was just inserted |
GPT_CALL_NO_FUNCTION |
The chat contained @housekeeper, so it called the OpenAI API, but no function call was detected |
GPT_CALL_FUNCTION |
The chat contained @housekeeper, so it called the OpenAI API, detected a function call, and executed the function |
Example
As stated previously, Firebase functions must be called from a registered app.
The ChatStore.swift file contains a few examples of using this function.
Get Chats
Function Identifier: getChats
The Get Chats Firebase function is used to get a well-formatted chat history from the room. It filters out function chats, orders the history as expected, and implements pagination.
Function Chats: Each chat in the Firestore database is assigned a role. There are five roles listed below:
Chat Role Displayed To User? Description roommateDisplayed Assigned to chats from users that did not invoke the Housekeeper userDisplayed Assigned to chats from users that did invoke the Housekeeper assistantDisplayed Assigned to plain chats (not function calls) that the Housekeeper created assistant-functionHidden Assigned to responses from the Housekeeper that invoked a function functionHidden Assigned to responses from a invoked function that are passed to the Housekeeper In order to be compatible with the OpenAI API, chats with the role assistant-function or function are kept in the database, only to be used to format the context that is sent to OpenAI.
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
roomId |
Firebase Document Id | The room to get the chat history for | Required |
maxTimestamp |
Date | Used for pagination. The function gets a maximum of 20 chats that are older than this time | Required |
minTimestamp |
Date | Used for pagination. The function gets all chats that are newer than this time | Required |
Returns
An object of the following form:
| Key | Type | Description |
|---|---|---|
olderHistory |
[Chat] | The (maximum of) 20 chats before the maxTimestamp |
newerHistory |
[Chat] | All chats after the minTimestamp |
A Chat consists of the following:
| Key | Type | Description |
|---|---|---|
content |
String | The content of the chat |
createdAt |
Date | The time the chat was sent |
role |
Enum | The role of the chat. Always one of ["roommate", "user", "assistant"] |
id |
Firebase Document Id | The Id of the chat |
userId |
Firebase Document Id | The Id of the sender (null if role is assistant) |
displayName |
String | The display name of the sender (null if role is assistant) |
profilePicture |
URL | A link to the sender's profile picture (or a link to a Block M if the role is assistant) |
Example
The ChatStore.swift file contains a few examples of using this function.
Calendar API
The Calendar API is how RoomieMatter communicates with the Google Calendar API. Functions in this API are called by both the client (in the case of a manual invocation of a Google Calendar function) or by the server (in the case that GPT decides to call a Google Calendar function)
There are two main ways that RoomieMatter uses Google Calendar: Chores and Events. Below are their corresponding Firebase functions.
Chores
- Get Chore (source code)
- Get Chores (source code)
- Add Chore (source code)
- Edit Chore (source code)
- Complete Chore (source code)
- Delete Chore (source code)
Events
- Get Events (source code)
- Add Event (source code)
- Edit Event (source code)
- Delete Event (source code)
Get Chore
Gets information about a chore
Function Identifier: getChore
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
instanceId |
Google Calendar Id | Id of the chore the user is getting information for | Required |
Returns
An object of the form {status, chore} where status is true upon success and chore is:
| Key | Type | Description |
|---|---|---|
instanceId |
Google Calendar Id | Id of the chore the user is getting information for |
eventName |
String | Title of the chore |
frequency |
Enum | How often the chore repeats. One of ["Once", "Daily", "Weekly", "Biweekly", "Monthly"] |
description |
String | A description of the chore |
assignedRoommates |
[userId] | An array of userIds of the roommates assigned to this chore |
Get Chores
Gets all chores for a room
Function Identifier: getChores
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
Returns
An object of the form {status, [chore]} where status is true upon success and chore is:
| Key | Type | Description |
|---|---|---|
instanceId |
Google Calendar Id | Id of the chore the user is getting information for |
eventName |
String | Title of the chore |
frequency |
Enum | How often the chore repeats. One of ["Once", "Daily", "Weekly", "Biweekly", "Monthly"] |
description |
String | A description of the chore |
assignedRoommates |
[userId] | An array of userIds of the roommates assigned to this chore |
Add Chore
Adds a chore
Function Identifier: addChore
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
eventName |
String | Title of the chore | Required |
date |
String | The date the chore is in YYYY-MM-DD form | Optional |
frequency |
Enum | How often the chore repeats. One of ["Once", "Daily", "Weekly", "Biweekly", "Monthly"] | Required |
endRecurrenceDate |
String | The date the chore stops repeating in YYYY-MM-DD form | Optional |
description |
String | A description of the chore | Optional |
assignedRoommates |
[userId] | An array of userIds of the roommates assigned to this chore | Optional |
Returns
An object of the form {status, instanceId} where status is true upon success and instanceId is the Google Calendar API Id of the newly added chore
Edit Chore
Edits a chore (edits all repeated instances)
Function Identifier: editChore
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
instanceId |
Google Calendar Id | Id of the chore the user is editing | Required |
eventName |
String | Title of the chore | Optional |
date |
String | The date the chore is in YYYY-MM-DD form | Optional |
frequency |
Enum | How often the chore repeats. One of ["Once", "Daily", "Weekly", "Biweekly", "Monthly"] | Optional |
endRecurrenceDate |
String | The date the chore stops repeating in YYYY-MM-DD form | Optional |
description |
String | A description of the chore | Optional |
assignedRoommates |
[userId] | An array of userIds of the roommates assigned to this chore | Optional |
Returns
An object of the form {status, chore} where status is true upon success and chore is:
| Key | Type | Description |
|---|---|---|
instanceId |
Google Calendar Id | Id of the chore the user is editing |
eventName |
String | Title of the chore |
frequency |
Enum | How often the chore repeats. One of ["Once", "Daily", "Weekly", "Biweekly", "Monthly"] |
description |
String | A description of the chore |
assignedRoommates |
[userId] | An array of userIds of the roommates assigned to this chore |
Complete Chore
Marks a single repetition of a chore as completed (effectively removing it)
Function Identifier: completeChore
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
instanceId |
Google Calendar Id | Id of the chore the user is marking as complete | Required |
Returns
An object of the form {status, nextInstanceId} where status is true upon success and nextInstanceId represents the Google Calendar API Id of the next repetition of this chore.
Delete Chore
Deletes every instance of a chore
Function Identifier: deleteChore
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the chore is in | Required |
instanceId |
Google Calendar Id | Id of the chore the user is getting information for | Required |
Returns
An object of the form {status} where status is true upon success
Get Events
Gets all events for a room
Function Identifier: getEvents
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the user is getting events for | Required |
Returns
An object of the form {status, [event]} where status is true upon success and event is:
| Key | Type | Description |
|---|---|---|
eventId |
Google Calendar Id | Id of the event the user is getting information for |
eventName |
String | Title of the event |
date |
String | The date the event is in YYYY-MM-DD form |
description |
String | A description of the event |
guests |
[userId] | An array of userIds of the roommates assigned to this event |
Add Event
Adds an event
Function Identifier: addEvent
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the event is in | Required |
eventName |
String | Title of the event | Required |
startDatetime |
Date | The date the event begins in ISO form | Required |
endDatetime |
Date | The date the event ends in ISO form | Required |
description |
String | A description of the event | Optional |
guests |
[userId] | An array of userIds of the roommates assigned to this event | Optional |
Returns
An object of the form {status, eventId} where status is true upon success and eventId is the Google Calendar API Id of the newly added event
Edit Event
Edits an event
Function Identifier: editEvent
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the event is in | Required |
eventId |
Google Calendar Id | Id of the event the user is editing | Required |
eventName |
String | Title of the event | Optional |
startDatetime |
Date | The date the event begins in ISO form | Optional |
endDatetime |
Date | The date the event ends in ISO form | Optional |
description |
String | A description of the event | Optional |
guests |
[userId] | An array of userIds of the roommates assigned to this event | Optional |
Returns
An object of the form {status, event} where status is true upon success and event is:
| Key | Type | Description |
|---|---|---|
eventId |
Google Calendar Id | Id of the event the user is getting information for |
eventName |
String | Title of the event |
date |
String | The date the event is in YYYY-MM-DD form |
description |
String | A description of the event |
guests |
[userId] | An array of userIds of the roommates assigned to this event |
Delete Event
Deletes an event
Function Identifier: deleteEvent
Request Parameters
| Key | Type | Description | Required? |
|---|---|---|---|
token |
Google oAuth Token | Used to trigger the Google Calendar API | Required |
roomId |
Firebase Document Id | The room the user is sending a message to | Required |
eventId |
Google Calendar Id | Id of the event the user is trying to delete | Required |
Returns
An object of the form {status} where status is true upon success
Third Party APIs & SDKs
OpenAI API
We use the OpenAI API. Specifically, we use the Chat Completions API with the gpt-3.5-turbo model (for cost purposes).
Function calling is supported with this endpoint. Read about it here
Google APIs
Google Calendar API
We use the Google Calendar API to manage chores and events.
Firebase SDK
We use the Firebase SDK in our frontend to connect to the database, authenticate users, and trigger backend functions. Our backend is built using Firebase.
Authentication
Due to the nature of Google Calendar, we require an oAuth token, but Firebase authentication (which uses Google as the provider) does not store this token. Instead, we use a mixture of both Google oAuth and Firebase Auth to authenticate users and enable access to their Google Calendar.