Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added documentation, SiteIntegrationAPI #568

Merged
merged 5 commits into from
Apr 15, 2024
Merged

added documentation, SiteIntegrationAPI #568

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e04eeb9
added documentation, SiteIntegrationAPI
kevinmram Dec 3, 2023
59c4d02
added docstring, rejectIDOLChanges
kevinmram Dec 3, 2023
e463082
Merge branch 'main' into si-api-documentation
keverie Apr 14, 2024
1b5e06b
added/edited suggested changes, prettier.
keverie Apr 14, 2024
6b2a126
yarn install, prettier
keverie Apr 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions backend/src/API/siteIntegrationAPI.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ import { PermissionError, BadRequestError } from '../utils/errors';

require('dotenv').config();

/**
* Triggers a dispatch event to pull changes from the IDOL backend.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be a little more specific about what this does.

e.g. Triggers a dispatch event for the pull-from-idol GitHub action. This job (blah blah blah brief description of what the job does).

* @param {IdolMember} user - The user requesting the pull dispatch.
* @returns {Promise<{updated: boolean}>} - A promise that resolves to an object indicating if the update was successful.
* @throws {PermissionError} - If the user lacks permission to trigger the dispatch.
*/
export const requestIDOLPullDispatch = async (user: IdolMember): Promise<{ updated: boolean }> => {
await checkPermissions(user);
const octokit = new Octokit({
Expand All @@ -19,12 +25,24 @@ export const requestIDOLPullDispatch = async (user: IdolMember): Promise<{ updat
return { updated: result.status === 204 };
};

/**
* Retrieves the latest Pull Request with changes from the IDOL backend.
* @param {IdolMember} user - The user requesting the pull request details.
* @returns {Promise<{pr: PRResponse}>} - A promise that resolves to an object containing the pull request details.
* @throws {PermissionError} - If the user lacks permission to access the pull request.
*/
export const getIDOLChangesPR = async (user: IdolMember): Promise<{ pr: PRResponse }> => {
await checkPermissions(user);
const foundPR = await findBotPR();
return { pr: foundPR };
};

/**
* Accepts and merges the IDOL backend changes pull request.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should mention what happens when the PR is merged (i.e. triggering a deploy).

* @param {IdolMember} user - The user attempting to accept the changes.
* @returns {Promise<{pr: PRResponse; merged: boolean}>} - A promise that resolves to an object containing the pull request details and a boolean indicating if the merge was successful.
* @throws {PermissionError} - If the user lacks permission to merge the pull request.
*/
export const acceptIDOLChanges = async (
user: IdolMember
): Promise<{ pr: PRResponse; merged: boolean }> => {
Expand Down Expand Up @@ -80,6 +98,11 @@ export const rejectIDOLChanges = async (
return { pr: foundPR, closed: closedReview.data.state === 'closed' };
};

/**
* Finds an open pull request created by a bot for updating IDOL backend data.
* @returns {Promise<PRResponse>} - A promise that resolves to the found pull request details.
* @throws {BadRequestError} - If no valid open pull request is found.
*/
const findBotPR = async (): Promise<PRResponse> => {
const octokit = new Octokit({
auth: `token ${process.env.BOT_TOKEN}`,
Expand All @@ -100,6 +123,12 @@ const findBotPR = async (): Promise<PRResponse> => {
return foundPR;
};

/**
* Checks if the user has permission to deploy the site.
* @param {IdolMember} user - The user whose permissions are being checked.
* @returns {Promise<void>} - A promise that resolves to void.
* @throws {PermissionError} - If the user does not have permission to deploy the site.
*/
const checkPermissions = async (user: IdolMember): Promise<void> => {
const canEdit = await PermissionsManager.canDeploySite(user);
if (!canEdit) {
Expand Down
Loading