#3873 edit platform description endpoints + frontend in recruitment admin tools

Author: staysgt

src/backend/src/controllers/organizations.controllers.ts

@@ -173,6 +173,20 @@ export default class OrganizationsController {
     }
   }
 
+  static async setPlatformDescription(req: Request, res: Response, next: NextFunction) {
+    try {
+      const updatedOrg = await OrganizationsService.setPlatformDescription(
+        req.body.platformDescription,
+        req.currentUser,
+        req.organization
+      );
+
+      res.status(200).json(updatedOrg);
+    } catch (error: unknown) {
+      next(error);
+    }
+  }
+
   static async getOrganizationFeaturedProjects(req: Request, res: Response, next: NextFunction) {
     try {
       const featuredProjects = await OrganizationsService.getOrganizationFeaturedProjects(req.organization.organizationId);

src/backend/src/routes/organizations.routes.ts

@@ -63,6 +63,12 @@ organizationRouter.post(
   validateInputs,
   OrganizationsController.setOrganizationDescription
 );
+organizationRouter.post(
+  '/platform-description/set',
+  body('platformDescription').isString(),
+  validateInputs,
+  OrganizationsController.setPlatformDescription
+);
 organizationRouter.get('/featured-projects', OrganizationsController.getOrganizationFeaturedProjects);
 organizationRouter.post(
   '/workspaceId/set',

src/backend/src/services/organizations.services.ts

@@ -378,6 +378,23 @@ export default class OrganizationsService {
     return updatedOrg;
   }
 
+  /**
+   * Sets the platform description of a given organization.
+   * @param platformDescription the new platform description
+   * @param submitter the user making the change
+   * @param organization the organization whose platform description is changing
+   * @throws if the user is not an admin
+   */
+  static async setPlatformDescription(platformDescription: string, submitter: User, organization: Organization) {
+    if (!(await userHasPermission(submitter.userId, organization.organizationId, isAdmin))) {
+      throw new AccessDeniedAdminOnlyException('set platform description');
+    }
+    return prisma.organization.update({
+      where: { organizationId: organization.organizationId },
+      data: { platformDescription }
+    });
+  }
+
   /**
    * Gets the featured projects for the given organization Id
    * @param organizationId the organization to get the projects for

src/backend/src/transformers/organizationTransformer.ts

@@ -6,6 +6,7 @@ export const organizationTransformer = (organization: Organization): Organizatio
     ...organization,
     applicationLink: organization.applicationLink ?? undefined,
     newMemberImageId: organization.newMemberImageId ?? undefined,
+    platformDescription: organization.platformDescription ?? '',
     platformLogoImageId: organization.platformLogoImageId ?? undefined
   };
 };

src/frontend/src/apis/organizations.api.ts

@@ -42,6 +42,12 @@ export const setOrganizationDescription = async (description: string) => {
   });
 };
 
+export const setPlatformDescription = async (platformDescription: string) => {
+  return axios.post<Organization>(apiUrls.organizationsSetPlatformDescription(), {
+    platformDescription
+  });
+};
+
 export const getOrganizationLogo = async () => {
   return axios.get<string>(apiUrls.organizationsLogoImage(), {
     transformResponse: (data) => JSON.parse(data)

src/frontend/src/hooks/organizations.hooks.ts

@@ -6,6 +6,7 @@ import {
   getFeaturedProjects,
   getCurrentOrganization,
   setOrganizationDescription,
+  setPlatformDescription,
   setOrganizationFeaturedProjects,
   setOrganizationWorkspaceId,
   setOrganizationLogo,
@@ -149,6 +150,22 @@ export const useSetOrganizationDescription = () => {
   );
 };
 
+export const useSetPlatformDescription = () => {
+  const queryClient = useQueryClient();
+  return useMutation<Organization, Error, string>(
+    ['organizations', 'platform-description'],
+    async (platformDescription: string) => {
+      const { data } = await setPlatformDescription(platformDescription);
+      return data;
+    },
+    {
+      onSuccess: () => {
+        queryClient.invalidateQueries(['organizations']);
+      }
+    }
+  );
+};
+
 export const useSetFeaturedProjects = () => {
   const queryClient = useQueryClient();
   return useMutation<Organization, Error, ProjectPreview[]>(

src/frontend/src/pages/AdminToolsPage/RecruitmentConfig/AdminToolsRecruitmentConfig.tsx

@@ -1,16 +1,29 @@
-import { Box, Grid, Typography } from '@mui/material';
+import { Box, FormControl, Grid, Typography } from '@mui/material';
 import MilestoneTable from './MilestoneTable';
 import FAQsTable from './FAQTable';
 import React, { useState } from 'react';
-import { useCurrentOrganization, useSetOrganizationPlatformLogoImage } from '../../../hooks/organizations.hooks';
+import { useForm } from 'react-hook-form';
+import { yupResolver } from '@hookform/resolvers/yup';
+import * as yup from 'yup';
+import {
+  useCurrentOrganization,
+  useSetOrganizationPlatformLogoImage,
+  useSetPlatformDescription
+} from '../../../hooks/organizations.hooks';
 import LoadingIndicator from '../../../components/LoadingIndicator';
 import ErrorPage from '../../ErrorPage';
 import ApplicationLinkTable from './ApplicationLinkTable';
 import { useGetImageUrl } from '../../../hooks/onboarding.hook';
 import NERUploadButton from '../../../components/NERUploadButton';
+import NERSuccessButton from '../../../components/NERSuccessButton';
+import ReactHookTextField from '../../../components/ReactHookTextField';
 import { useToast } from '../../../hooks/toasts.hooks';
 import { MAX_FILE_SIZE } from 'shared';
 
+const platformDescriptionSchema = yup.object().shape({
+  platformDescription: yup.string().required()
+});
+
 const AdminToolsRecruitmentConfig: React.FC = () => {
   const {
     data: organization,
@@ -20,13 +33,30 @@ const AdminToolsRecruitmentConfig: React.FC = () => {
   } = useCurrentOrganization();
 
   const { mutateAsync: setPlatformLogoImage, isLoading: platformLogoLoading } = useSetOrganizationPlatformLogoImage();
+  const { mutateAsync: setPlatformDescriptionMutation, isLoading: platformDescriptionSaving } = useSetPlatformDescription();
 
   const { data: platformLogoImageUrl } = useGetImageUrl(organization?.platformLogoImageId ?? null);
 
   const toast = useToast();
 
   const [addedPlatformLogo, setAddedPlatformLogo] = useState<File | undefined>(undefined);
 
+  const { control, handleSubmit, reset } = useForm<{ platformDescription: string }>({
+    resolver: yupResolver(platformDescriptionSchema),
+    defaultValues: { platformDescription: organization?.platformDescription ?? '' }
+  });
+  const formKey = organization?.organizationId ?? 'loading';
+
+  const onPlatformDescriptionSubmit = async (data: { platformDescription: string }) => {
+    try {
+      const updated = await setPlatformDescriptionMutation(data.platformDescription);
+      reset({ platformDescription: updated.platformDescription });
+      toast.success('Platform description saved.');
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : 'Failed to save platform description');
+    }
+  };
+
   const handlePlatformLogoUpload = async () => {
     if (!addedPlatformLogo) return;
     if (addedPlatformLogo.size >= MAX_FILE_SIZE) {
@@ -99,6 +129,47 @@ const AdminToolsRecruitmentConfig: React.FC = () => {
             </Box>
           )}
         </Grid>
+        <Grid item xs={12} md={6}>
+          <Typography variant="h5" gutterBottom borderBottom={1} color="#ef4345" borderColor="white">
+            Platform Description
+          </Typography>
+          <form
+            id="platform-description-form"
+            key={formKey}
+            onSubmit={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleSubmit(onPlatformDescriptionSubmit)(e);
+            }}
+            onKeyPress={(e) => {
+              e.key === 'Enter' && e.preventDefault();
+            }}
+          >
+            <FormControl sx={{ width: '100%' }}>
+              <ReactHookTextField
+                name="platformDescription"
+                control={control}
+                multiline
+                rows={5}
+                fullWidth
+                required
+                placeholder="Enter platform description for the guest home page..."
+                sx={{ mb: 1 }}
+              />
+            </FormControl>
+            <Box sx={{ display: 'flex', justifyContent: 'end' }}>
+              <NERSuccessButton
+                type="submit"
+                form="platform-description-form"
+                variant="contained"
+                disabled={platformDescriptionSaving}
+                sx={{ mt: 1 }}
+              >
+                {platformDescriptionSaving ? 'Saving...' : 'Save'}
+              </NERSuccessButton>
+            </Box>
+          </form>
+        </Grid>
       </Grid>
     </Box>
   );

src/frontend/src/utils/urls.ts

@@ -362,6 +362,7 @@ const organizationsUpdateContacts = () => `${organizations()}/contacts/set`;
 const organizationsSetOnboardingText = () => `${organizations()}/onboardingText/set`;
 const organizationsUpdateApplicationLink = () => `${organizations()}/application-link/update`;
 const organizationsSetDescription = () => `${organizations()}/description/set`;
+const organizationsSetPlatformDescription = () => `${organizations()}/platform-description/set`;
 const organizationsFeaturedProjects = () => `${organizations()}/featured-projects`;
 const organizationsLogoImage = () => `${organizations()}/logo`;
 const organizationsSetLogoImage = () => `${organizations()}/logo/update`;
@@ -725,6 +726,7 @@ export const apiUrls = {
   organizationsUpdateApplicationLink,
   organizationsFeaturedProjects,
   organizationsSetDescription,
+  organizationsSetPlatformDescription,
   organizationsLogoImage,
   organizationsSetLogoImage,
   organizationsNewMemberImage,

src/shared/src/types/user-types.ts

@@ -49,6 +49,7 @@ export type OrganizationPreview = Pick<
   | 'description'
   | 'applicationLink'
   | 'newMemberImageId'
+  | 'platformDescription'
   | 'platformLogoImageId'
 >;