Updated Event Docs

src/lib/api/handlers/events.ts

@@ -60,7 +60,17 @@ export const api = new Elysia({ prefix: "/events" })
       }),
       detail: {
         summary: "Get event detail",
-        description: "Gets the details of an event using it's eventId",
+        description: `Fetches the complete details of a specific event using its unique eventId.
+
+The eventId must be a valid numeric identifier.  
+Returns the event information if found.
+
+**Response Codes:**
+- **200**: Event details retrieved successfully
+- **401**: Unauthorized access
+- **404**: Event not found
+- **500**: Server error`,
+        tags: ["Events"],
       },
     },
   )
@@ -103,6 +113,25 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(EventsArraySchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Get all events",
+        description: `Fetches a list of events with optional date filtering and pagination.
+
+      Optional query parameters:
+      - **eventsFrom**: Filters events starting from this date (inclusive)
+      - **eventsTill**: Filters events up to this date (inclusive)
+      - **offset**: Number of records to skip (for pagination)
+      - **pageSize**: Number of records to return
+
+      If no filters are provided, all events are returned.
+
+      **Response Codes:**
+      - **200**: Events retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: Events not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .get(
@@ -144,6 +173,24 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(EventUserSchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Get events associated with a user",
+        description: `Fetches events linked to a specific user using their userId.
+
+      Optional query parameters:
+      - **role**: Filters events based on the user's role (e.g., participant, organiser, admin)
+      - **offset**: Number of records to skip (for pagination)
+      - **pageSize**: Number of records to return
+
+      Returns events where the specified user is associated in the given role (if provided).
+
+      **Response Codes:**
+      - **200**: User-associated events retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: User or events not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .get(
@@ -177,6 +224,22 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(BaseEventSchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Get next upcoming event",
+        description: `Fetches the next upcoming event relative to the provided date.
+
+      Query parameters:
+      - **date**: Reference date (ISO string format) from which the next event will be determined.
+
+      Returns the nearest upcoming event scheduled after the given date.
+
+      **Response Codes:**
+      - **200**: Next event retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: No upcoming event found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .get(
@@ -204,6 +267,22 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(BaseEventSchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Search events by pattern",
+        description: `Searches for events matching a given search pattern.
+
+      Query parameters:
+      - **query**: Search string used to match event fields (e.g., title, description, tags).
+
+      Returns events that match the provided search pattern.
+
+      **Response Codes:**
+      - **200**: Matching events retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: No matching events found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .get(
@@ -236,6 +315,23 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(EventsArraySchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Get ongoing events",
+        description: `Fetches events that are currently ongoing.
+
+      Optional query parameters:
+      - **offset**: Number of records to skip (for pagination)
+      - **pageSize**: Number of records to return
+
+      Returns events whose start and end times indicate they are currently in progress.
+
+      **Response Codes:**
+      - **200**: Ongoing events retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: No ongoing events found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .get(
@@ -274,6 +370,26 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(EventsArraySchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Get events by ACM branch",
+        description: `Fetches events organized under a specific ACM branch.
+
+      Path parameters:
+      - **branch**: One of the predefined ACM subgroups.
+
+      Optional query parameters:
+      - **offset**: Number of records to skip (for pagination)
+      - **pageSize**: Number of records to return
+
+      Returns events associated with the specified branch.
+
+      **Response Codes:**
+      - **200**: Branch events retrieved successfully
+      - **401**: Unauthorized access
+      - **404**: Branch or events not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .post(
@@ -315,6 +431,32 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(BaseEventSchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Create a new event",
+        description: `Creates a new event with the provided details.
+
+      Authentication is required. The request must include a valid Bearer token.
+
+      Request body:
+      - **id**: Unique event identifier
+      - **title**: Event title
+      - **branch**: Associated ACM branch
+      - **startDate**: Event start date and time
+      - **endDate**: Event end date and time
+      - **description**: Event description
+      - **relatedLink**: Optional external link related to the event
+      - **venue**: Event venue
+      - **ended**: Boolean indicating whether the event has concluded
+
+      Returns the created event details.
+
+      **Response Codes:**
+      - **200**: Event created successfully
+      - **401**: Unauthorized or invalid token
+      - **404**: Related resource not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .post(
@@ -363,6 +505,32 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(z.object({ message: z.string() }), {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Mark event as ended and send XP emails",
+        description: `Marks a specific event as ended and triggers email notifications with XP details to participants and contributors.
+
+      Authentication is required. The request must include a valid Bearer token.
+
+      Path parameters:
+      - **eventId**: Unique identifier of the event to be marked as ended.
+
+      Request body:
+      - **contributors**: List of contributor user identifiers or emails
+      - **publicity**: List of publicity team user identifiers or emails
+      - **participants**: List of participant user identifiers or emails
+      - **contributorsXp**: XP awarded to contributors
+      - **publicityXp**: XP awarded to publicity team members
+      - **participantXp**: XP awarded to participants
+
+      This action updates the event status to ended and dispatches corresponding email notifications.
+
+      **Response Codes:**
+      - **200**: Event marked as ended and emails processed successfully
+      - **401**: Unauthorized or invalid token
+      - **404**: Event not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .post(
@@ -409,6 +577,32 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(z.object({ message: z.string() }), {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Mark event as ended using SID and assign XP",
+        description: `Marks a specific event as ended and assigns XP to users identified by their SIDs.
+
+      Authentication is required. The request must include a valid Bearer token.
+
+      Path parameters:
+      - **eventId**: Unique identifier of the event to be marked as ended.
+
+      Request body:
+      - **contributors**: List of contributor SIDs
+      - **publicity**: List of publicity team SIDs
+      - **participants**: List of participant SIDs
+      - **contributorsXp**: XP awarded to contributors
+      - **publicityXp**: XP awarded to publicity team members
+      - **participantXp**: XP awarded to participants
+
+      This action updates the event status to ended and distributes XP based on the provided SID lists.
+
+      **Response Codes:**
+      - **200**: Event marked as ended and XP assigned successfully
+      - **401**: Unauthorized or invalid token
+      - **404**: Event not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .delete(
@@ -446,6 +640,24 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(z.object({ message: z.string() }), {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Delete event by ID",
+        description: `Deletes a specific event using its unique eventId.
+
+      Authentication is required. The request must include a valid Bearer token.
+
+      Path parameters:
+      - **id**: Unique identifier of the event to be deleted.
+
+      This action permanently removes the corresponding event.
+
+      **Response Codes:**
+      - **200**: Event deleted successfully
+      - **401**: Unauthorized or invalid token
+      - **404**: Event not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   )
   .put(
@@ -497,5 +709,34 @@ export const api = new Elysia({ prefix: "/events" })
       response: createResponseSchema(BaseEventSchema, {
         errorCodes: [401, 404, 500],
       }),
+      detail: {
+        summary: "Update event by ID",
+        description: `Updates the details of an existing event using its unique eventId.
+
+      Authentication is required. The request must include a valid Bearer token.
+
+      Path parameters:
+      - **eventId**: Unique identifier of the event to be updated.
+
+      Request body:
+      - **id**: Event identifier
+      - **title**: Event title
+      - **branch**: Associated ACM branch
+      - **startDate**: Event start date and time
+      - **endDate**: Event end date and time
+      - **description**: Event description
+      - **relatedLink**: Optional external link related to the event
+      - **venue**: Event venue
+      - **ended**: Boolean indicating whether the event has concluded
+
+      Returns the updated event details.
+
+      **Response Codes:**
+      - **200**: Event updated successfully
+      - **401**: Unauthorized or invalid token
+      - **404**: Event not found
+      - **500**: Server error`,
+        tags: ["Events"],
+      },
     },
   );