feat: ✨ add study room scraper and availability endpoint (#143)

Co-authored-by: Sanskar Mishra <[email protected]>

apps/api/bronya.config.ts

@@ -18,7 +18,7 @@ import { App, Stack, Duration } from "aws-cdk-lib/core";
 import { config } from "dotenv";
 import type { BuildOptions } from "esbuild";
 
-import { normalizeCourse } from "./src/lib/utils";
+import { normalizeCourse, normalizeStudyRoom } from "./src/lib/utils";
 
 const prisma = new PrismaClient();
 
@@ -121,6 +121,10 @@ export const esbuildOptions: BuildOptions = {
           path: args.path,
           namespace,
         }));
+        build.onResolve({ filter: /virtual:studyRooms/ }, (args) => ({
+          path: args.path,
+          namespace,
+        }));
         build.onLoad({ filter: /virtual:courses/, namespace }, async () => ({
           contents: `export const courses = ${JSON.stringify(
             Object.fromEntries(
@@ -133,6 +137,13 @@ export const esbuildOptions: BuildOptions = {
             Object.fromEntries((await prisma.instructor.findMany()).map((x) => [x.ucinetid, x])),
           )}`,
         }));
+        build.onLoad({ filter: /virtual:studyRooms/, namespace }, async () => ({
+          contents: `export const studyRooms = ${JSON.stringify(
+            Object.fromEntries(
+              (await prisma.studyRoom.findMany()).map(normalizeStudyRoom).map((x) => [x.id, x]),
+            ),
+          )}`,
+        }));
       },
     },
   ],

apps/api/src/global.d.ts

@@ -19,3 +19,8 @@ declare module "virtual:instructors" {
   // eslint-disable-next-line @typescript-eslint/consistent-type-imports
   declare const instructors: Record<string, import("@peterportal-api/types").Instructor>;
 }
+
+declare module "virtual:studyRooms" {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  declare const studyRooms: Record<string, import("@peterportal-api/types").StudyRoom>;
+}

apps/api/src/lib/utils.ts

@@ -1,11 +1,12 @@
-import type { Course as PrismaCourse } from "@libs/db";
+import type { Course as PrismaCourse, StudyRoom as PrismaStudyRoom } from "@libs/db";
 import type {
   Course,
   CourseLevel,
   CoursePreview,
   GECategory,
   InstructorPreview,
   PrerequisiteTree,
+  StudyRoom,
 } from "@peterportal-api/types";
 
 const days = ["Su", "M", "Tu", "W", "Th", "F", "Sa"];
@@ -82,3 +83,15 @@ export function normalizeCourse(course: PrismaCourse): Course {
     terms: course.terms,
   };
 }
+
+export function normalizeStudyRoom(room: PrismaStudyRoom): StudyRoom {
+  return {
+    id: room.id,
+    name: room.name,
+    capacity: room.capacity,
+    location: room.location,
+    description: room.description,
+    directions: room.directions,
+    techEnhanced: room.techEnhanced,
+  };
+}

apps/api/src/routes/v1/graphql/resolvers.ts

@@ -31,6 +31,8 @@ export const resolvers: ApolloServerOptions<BaseContext>["resolvers"] = {
     instructors: proxyRestApi("/v1/rest/instructors"),
     allInstructors: proxyRestApi("/v1/rest/instructors/all"),
     larc: proxyRestApi("/v1/rest/larc"),
+    studyRooms: proxyRestApi("/v1/rest/studyrooms"),
+    allStudyRooms: proxyRestApi("/v1/rest/studyrooms/all"),
     websoc: proxyRestApi("/v1/rest/websoc", { argsTransform: geTransform }),
     depts: proxyRestApi("/v1/rest/websoc/depts"),
     terms: proxyRestApi("/v1/rest/websoc/terms"),

apps/api/src/routes/v1/graphql/schema/studyRooms.graphql

@@ -0,0 +1,46 @@
+type TimeSlot {
+  "Date of the time slot (YYYY-MM-DD)."
+  date: String!
+  "Start time of the time slot (HH:MM)."
+  start: String!
+  "End time of the time slot (HH:MM)."
+  end: String!
+  "If the time slot is booked."
+  booked: Boolean!
+}
+
+type StudyRoom {
+  "ID of study room used by spaces.lib."
+  id: ID!
+  "Name of the study room and its room number."
+  name: String!
+  "Number of chairs in the study room."
+  capacity: Int!
+  "Name of study location."
+  location: String!
+  "Description of the study room."
+  description: String
+  "Directions to the study room."
+  directions: String
+  "Time slots for the study room."
+  timeSlots: [TimeSlot]!
+  "If the study room has TV or other tech enhancements."
+  techEnhanced: Boolean
+}
+
+type StudyLocation {
+  "ID of the study location using shortened name of the location."
+  id: ID!
+  "Location ID of the study location used by space.lib."
+  lid: String!
+  "Name of the study location."
+  name: String!
+  "Rooms in the study location."
+  rooms: [StudyRoom!]!
+}
+
+extend type Query {
+  "Fetch all study rooms."
+  allStudyRooms(start: String!, end: String!): [StudyLocation!]!
+  studyRooms(location: String!, start: String!, end: String!): StudyLocation!
+}

apps/api/src/routes/v1/rest/studyRooms/+endpoint.ts

@@ -0,0 +1,30 @@
+import { createHandler } from "@libs/lambda";
+import { studyLocations } from "libs/uc-irvine-lib/src/spaces";
+import { ZodError } from "zod";
+
+import { aggregateStudyRooms } from "./lib";
+import { QuerySchema } from "./schema";
+
+export const GET = createHandler(async (event, context, res) => {
+  const headers = event.headers;
+  const query = event.queryStringParameters;
+  const requestId = context.awsRequestId;
+  try {
+    const parsedQuery = QuerySchema.parse(query);
+    if (!studyLocations[parsedQuery.location]) {
+      return res.createErrorResult(404, `Location ${parsedQuery.location} not found`, requestId);
+    }
+    const studyRooms = await aggregateStudyRooms(
+      parsedQuery.location,
+      parsedQuery.start,
+      parsedQuery.end,
+    );
+    return res.createOKResult(studyRooms, headers, requestId);
+  } catch (e) {
+    if (e instanceof ZodError) {
+      const messages = e.issues.map((issue) => issue.message);
+      return res.createErrorResult(400, messages.join("; "), requestId);
+    }
+    return res.createErrorResult(400, e, requestId);
+  }
+});

apps/api/src/routes/v1/rest/studyRooms/lib.ts

@@ -0,0 +1,57 @@
+import { TimeSlot, StudyLocation } from "@peterportal-api/types";
+import { studyLocations } from "libs/uc-irvine-lib/src/spaces";
+import { getStudySpaces } from "libs/uc-irvine-lib/src/spaces";
+import { studyRooms } from "virtual:studyRooms";
+
+/**
+ * Data structure of time slots returned by libs.spaces.
+ */
+type Slot = {
+  start: string;
+  end: string;
+  itemId: number;
+  checkSum: string;
+  className: string;
+};
+
+/**
+ *  Map time slots to a more readable format.
+ */
+export function parseTimeSlots(slots: Slot[]): { [id: string]: TimeSlot[] } {
+  const timeSlots: { [id: string]: TimeSlot[] } = {};
+  slots.forEach((slot) => {
+    const roomId = slot.itemId.toString();
+    const [date, start] = slot.start.split(" ");
+    const [_, end] = slot.end.split(" ");
+    const timeSlot: TimeSlot = {
+      date,
+      start,
+      end,
+      booked: !!slot.className && slot.className === "s-lc-eq-checkout",
+    };
+    timeSlots[roomId] ??= []
+    timeSlots[roomId].push(timeSlot)
+  });
+  return timeSlots;
+}
+
+/**
+ *  Aggregate study rooms and their time slots into a StudyLocation object.
+ */
+export async function aggregateStudyRooms(
+  locationId: string,
+  start: string,
+  end: string,
+): Promise<StudyLocation> {
+  const spaces = await getStudySpaces(studyLocations[locationId].lid, start, end);
+  const timeSlotsMap = parseTimeSlots(spaces.slots);
+  return {
+    id: locationId,
+    ...studyLocations[locationId],
+    rooms: Object.entries(timeSlotsMap)
+      .filter(([id, _]) => studyRooms[id] != null)
+      .map(([id, timeSlots]) => {
+        return { ...studyRooms[id], timeSlots };
+      }),
+  };
+}

apps/api/src/routes/v1/rest/studyRooms/schema.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const QuerySchema = z.object({
+  location: z.string({ required_error: 'Parameter "location" not provided' }),
+  start: z
+    .string({ required_error: 'Parameter "start" not provided' })
+    .regex(/^\d{4}-\d{2}-\d{2}$/, { message: "Start date must be in YYYY-MM-DD format" }),
+  end: z
+    .string({ required_error: 'Parameter "end" not provided' })
+    .regex(/^\d{4}-\d{2}-\d{2}$/, { message: "End date must be in YYYY-MM-DD format" }),
+});
+
+export type Query = z.infer<typeof QuerySchema>;

apps/api/src/routes/v1/rest/studyRooms/{id}/+config.ts

@@ -0,0 +1,11 @@
+import type { ApiPropsOverride } from "@bronya.js/api-construct";
+
+import { esbuildOptions, constructs } from "../../../../../../bronya.config";
+
+export const overrides: ApiPropsOverride = {
+  esbuild: esbuildOptions,
+  constructs: {
+    functionPlugin: constructs.functionPlugin,
+    restApiProps: constructs.restApiProps,
+  },
+};

apps/api/src/routes/v1/rest/studyRooms/{id}/+endpoint.ts

@@ -0,0 +1,47 @@
+import { createHandler } from "@libs/lambda";
+import { studyLocations } from "libs/uc-irvine-lib/src/spaces";
+import { ZodError } from "zod";
+
+import { aggregateStudyRooms } from "../lib";
+
+import { QuerySchema } from "./schema";
+
+export const GET = createHandler(async (event, context, res) => {
+  const headers = event.headers;
+  const query = event.queryStringParameters;
+  const requestId = context.awsRequestId;
+  const { id } = event.pathParameters ?? {};
+  try {
+    switch (id) {
+      case null:
+      case undefined:
+        return res.createErrorResult(400, "Location not provided", requestId);
+      case "all": {
+        const parsedQuery = QuerySchema.parse(query);
+        return res.createOKResult(
+          await Promise.all(
+            Object.keys(studyLocations).map(async (locationId) => {
+              return aggregateStudyRooms(locationId, parsedQuery.start, parsedQuery.end);
+            }),
+          ),
+          headers,
+          requestId,
+        );
+      }
+      default: {
+        if (studyLocations[id]) {
+          const parsedQuery = QuerySchema.parse(query);
+          const studyRooms = await aggregateStudyRooms(id, parsedQuery.start, parsedQuery.end);
+          return res.createOKResult(studyRooms, headers, requestId);
+        }
+        return res.createErrorResult(400, `Location ${id} not found`, requestId);
+      }
+    }
+  } catch (e) {
+    if (e instanceof ZodError) {
+      const messages = e.issues.map((issue) => issue.message);
+      return res.createErrorResult(400, messages.join("; "), requestId);
+    }
+    return res.createErrorResult(400, e, requestId);
+  }
+});

apps/api/src/routes/v1/rest/studyRooms/{id}/schema.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+export const QuerySchema = z.object({
+  start: z
+    .string({ required_error: 'Parameter "start" not provided' })
+    .regex(/^\d{4}-\d{2}-\d{2}$/, { message: "Start date must be in YYYY-MM-DD format" }),
+  end: z
+    .string({ required_error: 'Parameter "end" not provided' })
+    .regex(/^\d{4}-\d{2}-\d{2}$/, { message: "End date must be in YYYY-MM-DD format" }),
+});
+
+export type Query = z.infer<typeof QuerySchema>;