Merge branch 'master' of https://github.com/JarshiganK/Eventstack_Event_Management_System into dir

Author: JarshiganK

eventstack/apps/backend/src/routes/bookmarks.ts

@@ -1,14 +1,39 @@
+/**
+ * Bookmark routes module
+ * Handles all HTTP endpoints related to user bookmarks, including:
+ * - Retrieving a user's bookmarked events
+ * - Adding events to user's bookmarks
+ * - Removing events from user's bookmarks
+ * All endpoints require user authentication
+ */
 import { FastifyInstance } from "fastify";
 import { z } from "zod";
 import { query } from "../db.js";
 import { cuid } from "../utils.js";
 import { requireUser } from "../auth.js";
 
+/**
+ * Registers all bookmark-related routes with the Fastify app instance
+ * @param app - Fastify application instance
+ */
 export default async function bookmarkRoutes(app: FastifyInstance) {
+  /**
+   * Schema for validating bookmark creation requests
+   * Requires an eventId field to identify which event to bookmark
+   */
   const addSchema = z.object({ eventId: z.string() });
 
+  /**
+   * GET /me/bookmarks
+   * Retrieves all bookmarked events for the authenticated user
+   * Returns events in reverse chronological order (most recently bookmarked first)
+   * Includes event details and the first cover image URL
+   * @returns Array of event objects with id, title, summary, dates, coverUrl, and venue
+   */
   app.get("/me/bookmarks", { preHandler: requireUser }, async (req) => {
     const user = (req as any).user as { id: string };
+    // Query joins bookmarks with events to get full event details
+    // Gets the first cover image ordered by display order
     const { rows } = await query(
       `SELECT b.event_id as id, e.title, e.summary, e.starts_at, e.ends_at,
               (SELECT url FROM event_images i WHERE i.event_id=e.id ORDER BY ord ASC LIMIT 1) as cover_url,
@@ -19,6 +44,7 @@ export default async function bookmarkRoutes(app: FastifyInstance) {
        ORDER BY b.created_at DESC`,
       [user.id]
     );
+    // Transform database rows to API response format with ISO date strings
     return rows.map((r: any) => ({
       id: r.id,
       title: r.title,
@@ -30,22 +56,38 @@ export default async function bookmarkRoutes(app: FastifyInstance) {
     }));
   });
 
+  /**
+   * POST /me/bookmarks
+   * Adds an event to the authenticated user's bookmarks
+   * If the event is already bookmarked, the request silently succeeds (idempotent)
+   * @param body.eventId - The ID of the event to bookmark
+   * @returns 201 status with success confirmation
+   */
   app.post("/me/bookmarks", { preHandler: requireUser }, async (req, reply) => {
     const body = addSchema.parse(req.body);
     const user = (req as any).user as { id: string };
     try {
+      // Create a new bookmark with a generated CUID
       await query(
         `INSERT INTO bookmarks (id, user_id, event_id) VALUES ($1,$2,$3)`,
         [cuid(), user.id, body.eventId]
       );
     } catch (e: any) {
-      // likely duplicate
+      // If bookmark already exists (duplicate key), silently ignore the error
+      // This makes the endpoint idempotent - calling it multiple times is safe
     }
     reply.code(201).send({ ok: true });
   });
 
+  /**
+   * DELETE /me/bookmarks/:eventId
+   * Removes an event from the authenticated user's bookmarks
+   * @param eventId - The ID of the event to remove from bookmarks (URL parameter)
+   * @returns Success confirmation object
+   */
   app.delete<{ Params: { eventId: string } }>("/me/bookmarks/:eventId", { preHandler: requireUser }, async (req) => {
     const user = (req as any).user as { id: string };
+    // Delete the bookmark matching both user and event IDs
     await query(`DELETE FROM bookmarks WHERE user_id=$1 AND event_id=$2`, [user.id, req.params.eventId]);
     return { ok: true };
   });

eventstack/apps/backend/src/routes/events.ts

@@ -1,10 +1,26 @@
+/**
+ * Event routes module
+ * Handles all HTTP endpoints related to events, including:
+ * - Retrieving event lists with filtering capabilities
+ * - Getting individual event details with images
+ * - Creating, updating, and deleting events (admin/organizer only)
+ * - Managing event images (admin/organizer only)
+ */
 import { FastifyInstance } from "fastify";
 import { z } from "zod";
 import { query } from "../db.js";
 import { cuid, iso } from "../utils.js";
 import { requireOrganizerOrAdmin } from "../auth.js";
 
+/**
+ * Registers all event-related routes with the Fastify app instance
+ * @param app - Fastify application instance
+ */
 export default async function eventRoutes(app: FastifyInstance) {
+  /**
+   * Base schema for event creation and updates
+   * Validates common fields required for event operations
+   */
   const baseSchema = z.object({
     title: z.string().min(1),
     summary: z.string().optional().nullable(),
@@ -14,10 +30,22 @@ export default async function eventRoutes(app: FastifyInstance) {
     categoriesCsv: z.string().optional().default("")
   });
 
+  /**
+   * GET /events
+   * Retrieves a list of events with optional filtering
+   * Query parameters:
+   *   - from: Filter events starting from this date (ISO string)
+   *   - to: Filter events ending before this date (ISO string)
+   *   - category: Filter events by category name
+   * @returns Array of event objects with cover image URL
+   */
   app.get("/events", async (req) => {
+    // Extract and parse query parameters for filtering
     const q = (req.query || {}) as Record<string, string | undefined>;
     const where: string[] = [];
     const params: any[] = [];
+    
+    // Build WHERE clause dynamically based on query parameters
     if (q.from) {
       params.push(q.from);
       where.push(`starts_at >= $${params.length}`);
@@ -28,9 +56,12 @@ export default async function eventRoutes(app: FastifyInstance) {
     }
     if (q.category) {
       params.push(q.category);
+      // Use PostgreSQL ANY() operator to check if category exists in categories array
       where.push(`$${params.length} = ANY(categories)`);
     }
     const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    
+    // Fetch events with their cover image (first image ordered by ord)
     const { rows } = await query(
       `SELECT e.*,
               (SELECT url FROM event_images i WHERE i.event_id=e.id ORDER BY ord ASC LIMIT 1) as cover_url
@@ -39,20 +70,31 @@ export default async function eventRoutes(app: FastifyInstance) {
        ORDER BY starts_at ASC`,
       params
     );
+    
+    // Transform database rows to API response format
     return rows.map((r: any) => ({
       id: r.id,
       title: r.title,
       summary: r.summary,
-      startsAt: iso(r.starts_at),
+      startsAt: iso(r.starts_at), // Convert PostgreSQL timestamp to ISO string
       endsAt: iso(r.ends_at),
       categories: r.categories || [],
       coverUrl: r.cover_url || undefined,
       venue: { name: r.venue_name }
     }));
   });
 
+  /**
+   * GET /events/:id
+   * Retrieves detailed information about a specific event
+   * Includes all event images ordered by their display order
+   * @param id - Event ID from URL parameter
+   * @returns Event object with all images, or 404 if not found
+   */
   app.get<{ Params: { id: string } }>("/events/:id", async (req, reply) => {
     const { id } = req.params;
+    
+    // Fetch event with cover image (first image)
     const { rows } = await query(
       `SELECT e.* , e.cover_url FROM (
         SELECT e.*, (SELECT url FROM event_images i WHERE i.event_id=e.id ORDER BY ord ASC LIMIT 1) as cover_url FROM events e
@@ -64,7 +106,10 @@ export default async function eventRoutes(app: FastifyInstance) {
       reply.code(404).send({ error: "Not found" });
       return;
     }
+    
+    // Fetch all images for this event, ordered by display order
     const { rows: img } = await query(`SELECT * FROM event_images WHERE event_id=$1 ORDER BY ord ASC`, [id]);
+    
     return {
       id: r.id,
       title: r.title,
@@ -77,35 +122,61 @@ export default async function eventRoutes(app: FastifyInstance) {
     };
   });
 
+  /**
+   * POST /admin/events
+   * Creates a new event (admin/organizer only)
+   * Requires authentication with organizer or admin role
+   * @param body - Event data validated against baseSchema
+   * @returns Object with the created event ID
+   */
   app.post("/admin/events", { preHandler: requireOrganizerOrAdmin }, async (req) => {
     const body = baseSchema.parse(req.body);
-    const id = cuid();
+    const id = cuid(); // Generate unique ID for the event
+    
+    // Parse comma-separated categories into array, trimming whitespace
     const categories = body.categoriesCsv ? body.categoriesCsv.split(",").map((s) => s.trim()).filter(Boolean) : [];
     const venueName = body.venueName || '';
+    
+    // Create searchable text by combining all searchable fields (for full-text search)
     const searchable = [body.title, body.summary ?? "", venueName, categories.join(" ")].join(" ").toLowerCase();
+    
     await query(
       `INSERT INTO events (id,title,summary,starts_at,ends_at,venue_name,categories,searchable) VALUES ($1,$2,$3,$4,$5,$6,$7,$8)`,
       [id, body.title, body.summary ?? null, body.startsAt, body.endsAt, venueName, categories, searchable]
     );
     return { id };
   });
 
+  /**
+   * POST /admin/events/:id/images
+   * Adds an image to an event (admin/organizer only)
+   * Images are automatically ordered based on existing images
+   * @param id - Event ID from URL parameter
+   * @param body - Image data (url, optional width/height)
+   * @returns Object with image ID, URL, and display order
+   */
   app.post<{ Params: { id: string } }>("/admin/events/:id/images", { preHandler: requireOrganizerOrAdmin }, async (req, reply) => {
     const { id: eventId } = req.params;
+    
+    // Schema for image validation
     const imageSchema = z.object({
       url: z.string().min(1),
       width: z.number().int().positive().optional(),
       height: z.number().int().positive().optional()
     });
     const body = imageSchema.parse(req.body);
 
+    // Verify that the event exists
     const { rows: existing } = await query("SELECT id FROM events WHERE id=$1", [eventId]);
     if (!existing.length) {
       reply.code(404).send({ error: "Event not found" });
       return;
     }
 
     const imageId = cuid();
+    
+    // Get the maximum order value for existing images, defaulting to -1 if none exist
+    // This ensures the new image is appended to the end
     const { rows: ordRows } = await query<{ max: number }>("SELECT COALESCE(MAX(ord), -1) as max FROM event_images WHERE event_id=$1", [eventId]);
     const nextOrd = (ordRows[0]?.max ?? -1) + 1;
 
@@ -117,19 +188,39 @@ export default async function eventRoutes(app: FastifyInstance) {
     return { id: imageId, url: body.url, ord: nextOrd };
   });
 
+  /**
+   * PUT /admin/events/:id
+   * Updates an existing event (admin/organizer only)
+   * Updates the updated_at timestamp automatically
+   * @param id - Event ID from URL parameter
+   * @param body - Event data validated against baseSchema
+   * @returns Object with the updated event ID
+   */
   app.put<{ Params: { id: string } }>("/admin/events/:id", { preHandler: requireOrganizerOrAdmin }, async (req) => {
     const body = baseSchema.parse(req.body);
     const { id } = req.params;
+    
+    // Parse comma-separated categories into array, trimming whitespace
     const categories = body.categoriesCsv ? body.categoriesCsv.split(",").map((s) => s.trim()).filter(Boolean) : [];
     const venueName = body.venueName || '';
+    
+    // Update searchable text by combining all searchable fields
     const searchable = [body.title, body.summary ?? "", venueName, categories.join(" ")].join(" ").toLowerCase();
+    
     await query(
       `UPDATE events SET title=$2,summary=$3,starts_at=$4,ends_at=$5,venue_name=$6,categories=$7,searchable=$8,updated_at=now() WHERE id=$1`,
       [id, body.title, body.summary ?? null, body.startsAt, body.endsAt, venueName, categories, searchable]
     );
     return { id };
   });
 
+  /**
+   * DELETE /admin/events/:id
+   * Deletes an event (admin/organizer only)
+   * Cascades to delete associated images and other related data
+   * @param id - Event ID from URL parameter
+   * @returns Object with the deleted event ID
+   */
   app.delete<{ Params: { id: string } }>("/admin/events/:id", { preHandler: requireOrganizerOrAdmin }, async (req) => {
     const { id } = req.params;
     await query(`DELETE FROM events WHERE id=$1`, [id]);

eventstack/apps/frontend/src/lib/api/events.ts

@@ -1,5 +1,17 @@
+/**
+ * Events API client module
+ * Provides functions to interact with the events API endpoints
+ */
 import { http } from "../http"
 
+/**
+ * Retrieves a list of events with optional filtering
+ * @param params - Optional filter parameters
+ * @param params.from - Filter events starting from this date (ISO string)
+ * @param params.to - Filter events ending before this date (ISO string)
+ * @param params.category - Filter events by category name
+ * @returns Promise resolving to an array of event objects
+ */
 export async function listEvents(params?: { from?: string; to?: string; category?: string }) {
   const qs = new URLSearchParams()
   if (params?.from) qs.set('from', params.from)
@@ -9,22 +21,63 @@ export async function listEvents(params?: { from?: string; to?: string; category
   return http<any[]>(`/events${q ? `?${q}` : ''}`)
 }
 
+/**
+ * Retrieves detailed information about a specific event
+ * @param id - Event ID
+ * @returns Promise resolving to an event object with all images
+ */
 export async function getEvent(id: string) { return http<any>(`/events/${id}`) }
 
+/**
+ * Creates a new event (admin/organizer only)
+ * Requires authentication with organizer or admin role
+ * @param e - Event data object
+ * @param e.title - Event title (required)
+ * @param e.summary - Event summary (optional)
+ * @param e.startsAt - Event start date/time (ISO string)
+ * @param e.endsAt - Event end date/time (ISO string)
+ * @param e.venueName - Venue name (optional)
+ * @param e.categoriesCsv - Comma-separated list of categories (optional)
+ * @returns Promise resolving to an object with the created event ID
+ */
 export async function createEvent(e: { title: string; summary?: string; startsAt: string; endsAt: string; venueName?: string; categoriesCsv?: string }) {
   return http<{ id: string }>(
     '/admin/events', { method: 'POST', body: JSON.stringify(e) }
   )
 }
 
+/**
+ * Updates an existing event (admin/organizer only)
+ * Requires authentication with organizer or admin role
+ * @param id - Event ID to update
+ * @param e - Event data object with fields to update
+ * @returns Promise resolving to an object with the updated event ID
+ */
 export async function updateEvent(id: string, e: { title: string; summary?: string; startsAt: string; endsAt: string; venueName?: string; categoriesCsv?: string }) {
   return http<{ id: string }>(
     `/admin/events/${id}`, { method: 'PUT', body: JSON.stringify(e) }
   )
 }
 
+/**
+ * Deletes an event (admin/organizer only)
+ * Requires authentication with organizer or admin role
+ * @param id - Event ID to delete
+ * @returns Promise resolving to an object with the deleted event ID
+ */
 export async function deleteEvent(id: string) { return http<{ id: string }>(`/admin/events/${id}`, { method: 'DELETE' }) }
 
+/**
+ * Adds an image to an event (admin/organizer only)
+ * Requires authentication with organizer or admin role
+ * Images are automatically ordered based on existing images
+ * @param id - Event ID
+ * @param image - Image data object
+ * @param image.url - Image URL (required)
+ * @param image.width - Image width in pixels (optional)
+ * @param image.height - Image height in pixels (optional)
+ * @returns Promise resolving to an object with image ID, URL, and display order
+ */
 export async function addEventImage(id: string, image: { url: string; width?: number; height?: number }) {
   return http<{ id: string; url: string; ord: number }>(
     `/admin/events/${id}/images`,