@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.0

package/src/services/calendar/utils/calendar-event.utils.ts

@@ -1,676 +1,676 @@
-import {
-  collection,
-  doc,
-  getDoc,
-  getDocs,
-  setDoc,
-  updateDoc,
-  deleteDoc,
-  query,
-  where,
-  orderBy,
-  Timestamp,
-  serverTimestamp,
-  Firestore,
-  DocumentReference,
-  QueryConstraint,
-} from "firebase/firestore";
-import {
-  CalendarEvent,
-  CalendarEventStatus,
-  CalendarEventTime,
-  CalendarEventType,
-  CalendarSyncStatus,
-  CreateCalendarEventData,
-  UpdateCalendarEventData,
-  CALENDAR_COLLECTION,
-  SearchCalendarEventsParams,
-  SearchLocationEnum,
-} from "../../../types/calendar";
-import { PRACTITIONERS_COLLECTION } from "../../../types/practitioner";
-import { PATIENTS_COLLECTION } from "../../../types/patient";
-import { CLINICS_COLLECTION } from "../../../types/clinic";
-
-/**
- * Creates a calendar event for a practitioner
- * @param db - Firestore instance
- * @param practitionerId - ID of the practitioner
- * @param eventData - Calendar event data
- * @param generateId - Function to generate a unique ID
- * @returns Created calendar event
- */
-export async function createPractitionerCalendarEventUtil(
-  db: Firestore,
-  practitionerId: string,
-  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
-  generateId: () => string
-): Promise<CalendarEvent> {
-  // TODO: Add validation for event data
-  // - Check if practitioner exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-  // - Validate required fields
-
-  const eventId = generateId();
-  const eventRef = doc(
-    db,
-    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const newEvent: CreateCalendarEventData = {
-    id: eventId,
-    ...eventData,
-    createdAt: serverTimestamp(),
-    updatedAt: serverTimestamp(),
-  };
-
-  await setDoc(eventRef, newEvent);
-
-  // Convert server timestamp to Timestamp for return value
-  return {
-    ...newEvent,
-    createdAt: Timestamp.now(),
-    updatedAt: Timestamp.now(),
-  } as CalendarEvent;
-}
-
-/**
- * Creates a calendar event for a patient
- * @param db - Firestore instance
- * @param patientId - ID of the patient
- * @param eventData - Calendar event data
- * @param generateId - Function to generate a unique ID
- * @returns Created calendar event
- */
-export async function createPatientCalendarEventUtil(
-  db: Firestore,
-  patientId: string,
-  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
-  generateId: () => string
-): Promise<CalendarEvent> {
-  // TODO: Add validation for event data
-  // - Check if patient exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-  // - Validate required fields
-
-  const eventId = generateId();
-  const eventRef = doc(
-    db,
-    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const newEvent: CreateCalendarEventData = {
-    id: eventId,
-    ...eventData,
-    createdAt: serverTimestamp(),
-    updatedAt: serverTimestamp(),
-  };
-
-  await setDoc(eventRef, newEvent);
-
-  // Convert server timestamp to Timestamp for return value
-  return {
-    ...newEvent,
-    createdAt: Timestamp.now(),
-    updatedAt: Timestamp.now(),
-  } as CalendarEvent;
-}
-
-/**
- * Creates a calendar event for a clinic
- * @param db - Firestore instance
- * @param clinicId - ID of the clinic
- * @param eventData - Calendar event data
- * @param generateId - Function to generate a unique ID
- * @returns Created calendar event
- */
-export async function createClinicCalendarEventUtil(
-  db: Firestore,
-  clinicId: string,
-  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
-  generateId: () => string
-): Promise<CalendarEvent> {
-  // TODO: Add validation for event data
-  // - Check if clinic exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-  // - Validate required fields
-
-  const eventId = generateId();
-  const eventRef = doc(
-    db,
-    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const newEvent: CreateCalendarEventData = {
-    id: eventId,
-    ...eventData,
-    createdAt: serverTimestamp(),
-    updatedAt: serverTimestamp(),
-  };
-
-  await setDoc(eventRef, newEvent);
-
-  // Convert server timestamp to Timestamp for return value
-  return {
-    ...newEvent,
-    createdAt: Timestamp.now(),
-    updatedAt: Timestamp.now(),
-  } as CalendarEvent;
-}
-
-/**
- * Gets a calendar event for a practitioner
- * @param db - Firestore instance
- * @param practitionerId - ID of the practitioner
- * @param eventId - ID of the event
- * @returns Calendar event or null if not found
- */
-export async function getPractitionerCalendarEventUtil(
-  db: Firestore,
-  practitionerId: string,
-  eventId: string
-): Promise<CalendarEvent | null> {
-  const eventRef = doc(
-    db,
-    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  const eventDoc = await getDoc(eventRef);
-
-  if (!eventDoc.exists()) {
-    return null;
-  }
-
-  return eventDoc.data() as CalendarEvent;
-}
-
-/**
- * Gets a calendar event for a patient
- * @param db - Firestore instance
- * @param patientId - ID of the patient
- * @param eventId - ID of the event
- * @returns Calendar event or null if not found
- */
-export async function getPatientCalendarEventUtil(
-  db: Firestore,
-  patientId: string,
-  eventId: string
-): Promise<CalendarEvent | null> {
-  const eventRef = doc(
-    db,
-    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  const eventDoc = await getDoc(eventRef);
-
-  if (!eventDoc.exists()) {
-    return null;
-  }
-
-  return eventDoc.data() as CalendarEvent;
-}
-
-/**
- * Gets a calendar event for a clinic
- * @param db - Firestore instance
- * @param clinicId - ID of the clinic
- * @param eventId - ID of the event
- * @returns Calendar event or null if not found
- */
-export async function getClinicCalendarEventUtil(
-  db: Firestore,
-  clinicId: string,
-  eventId: string
-): Promise<CalendarEvent | null> {
-  const eventRef = doc(
-    db,
-    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  const eventDoc = await getDoc(eventRef);
-
-  if (!eventDoc.exists()) {
-    return null;
-  }
-
-  return eventDoc.data() as CalendarEvent;
-}
-
-/**
- * Gets calendar events for a practitioner within a date range
- * @param db - Firestore instance
- * @param practitionerId - ID of the practitioner
- * @param startDate - Start date of the range
- * @param endDate - End date of the range
- * @returns Array of calendar events
- */
-export async function getPractitionerCalendarEventsUtil(
-  db: Firestore,
-  practitionerId: string,
-  startDate: Date,
-  endDate: Date
-): Promise<CalendarEvent[]> {
-  const startTimestamp = Timestamp.fromDate(startDate);
-  const endTimestamp = Timestamp.fromDate(endDate);
-
-  const eventsRef = collection(
-    db,
-    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}`
-  );
-
-  const q = query(
-    eventsRef,
-    where("eventTime.start", ">=", startTimestamp),
-    where("eventTime.end", "<=", endTimestamp),
-    orderBy("eventTime.start", "asc")
-  );
-
-  const querySnapshot = await getDocs(q);
-  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
-}
-
-/**
- * Gets calendar events for a patient within a date range
- * @param db - Firestore instance
- * @param patientId - ID of the patient
- * @param startDate - Start date of the range
- * @param endDate - End date of the range
- * @returns Array of calendar events
- */
-export async function getPatientCalendarEventsUtil(
-  db: Firestore,
-  patientId: string,
-  startDate: Date,
-  endDate: Date
-): Promise<CalendarEvent[]> {
-  const startTimestamp = Timestamp.fromDate(startDate);
-  const endTimestamp = Timestamp.fromDate(endDate);
-
-  const eventsRef = collection(
-    db,
-    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}`
-  );
-
-  const q = query(
-    eventsRef,
-    where("eventTime.start", ">=", startTimestamp),
-    where("eventTime.end", "<=", endTimestamp),
-    orderBy("eventTime.start", "asc")
-  );
-
-  const querySnapshot = await getDocs(q);
-  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
-}
-
-/**
- * Gets calendar events for a clinic within a date range
- * @param db - Firestore instance
- * @param clinicId - ID of the clinic
- * @param startDate - Start date of the range
- * @param endDate - End date of the range
- * @returns Array of calendar events
- */
-export async function getClinicCalendarEventsUtil(
-  db: Firestore,
-  clinicId: string,
-  startDate: Date,
-  endDate: Date
-): Promise<CalendarEvent[]> {
-  const startTimestamp = Timestamp.fromDate(startDate);
-  const endTimestamp = Timestamp.fromDate(endDate);
-
-  const eventsRef = collection(
-    db,
-    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}`
-  );
-
-  const q = query(
-    eventsRef,
-    where("eventTime.start", ">=", startTimestamp),
-    where("eventTime.end", "<=", endTimestamp),
-    orderBy("eventTime.start", "asc")
-  );
-
-  const querySnapshot = await getDocs(q);
-  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
-}
-
-/**
- * Updates a calendar event for a practitioner
- * @param db - Firestore instance
- * @param practitionerId - ID of the practitioner
- * @param eventId - ID of the event
- * @param updateData - Data to update
- * @returns Updated calendar event
- */
-export async function updatePractitionerCalendarEventUtil(
-  db: Firestore,
-  practitionerId: string,
-  eventId: string,
-  updateData: Omit<UpdateCalendarEventData, "updatedAt">
-): Promise<CalendarEvent> {
-  // TODO: Add validation for update data
-  // - Check if event exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-
-  const eventRef = doc(
-    db,
-    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const updates: UpdateCalendarEventData = {
-    ...updateData,
-    updatedAt: serverTimestamp(),
-  };
-
-  await updateDoc(eventRef, updates as any);
-
-  // Get the updated document
-  const updatedDoc = await getDoc(eventRef);
-
-  if (!updatedDoc.exists()) {
-    throw new Error("Event not found after update");
-  }
-
-  return updatedDoc.data() as CalendarEvent;
-}
-
-/**
- * Updates a calendar event for a patient
- * @param db - Firestore instance
- * @param patientId - ID of the patient
- * @param eventId - ID of the event
- * @param updateData - Data to update
- * @returns Updated calendar event
- */
-export async function updatePatientCalendarEventUtil(
-  db: Firestore,
-  patientId: string,
-  eventId: string,
-  updateData: Omit<UpdateCalendarEventData, "updatedAt">
-): Promise<CalendarEvent> {
-  // TODO: Add validation for update data
-  // - Check if event exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-
-  const eventRef = doc(
-    db,
-    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const updates: UpdateCalendarEventData = {
-    ...updateData,
-    updatedAt: serverTimestamp(),
-  };
-
-  await updateDoc(eventRef, updates as any);
-
-  // Get the updated document
-  const updatedDoc = await getDoc(eventRef);
-
-  if (!updatedDoc.exists()) {
-    throw new Error("Event not found after update");
-  }
-
-  return updatedDoc.data() as CalendarEvent;
-}
-
-/**
- * Updates a calendar event for a clinic
- * @param db - Firestore instance
- * @param clinicId - ID of the clinic
- * @param eventId - ID of the event
- * @param updateData - Data to update
- * @returns Updated calendar event
- */
-export async function updateClinicCalendarEventUtil(
-  db: Firestore,
-  clinicId: string,
-  eventId: string,
-  updateData: Omit<UpdateCalendarEventData, "updatedAt">
-): Promise<CalendarEvent> {
-  // TODO: Add validation for update data
-  // - Check if event exists
-  // - Validate event time (start < end)
-  // - Check for overlapping events
-
-  const eventRef = doc(
-    db,
-    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-
-  const updates: UpdateCalendarEventData = {
-    ...updateData,
-    updatedAt: serverTimestamp(),
-  };
-
-  await updateDoc(eventRef, updates as any);
-
-  // Get the updated document
-  const updatedDoc = await getDoc(eventRef);
-
-  if (!updatedDoc.exists()) {
-    throw new Error("Event not found after update");
-  }
-
-  return updatedDoc.data() as CalendarEvent;
-}
-
-/**
- * Deletes a calendar event for a practitioner
- * @param db - Firestore instance
- * @param practitionerId - ID of the practitioner
- * @param eventId - ID of the event
- */
-export async function deletePractitionerCalendarEventUtil(
-  db: Firestore,
-  practitionerId: string,
-  eventId: string
-): Promise<void> {
-  const eventRef = doc(
-    db,
-    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  await deleteDoc(eventRef);
-}
-
-/**
- * Deletes a calendar event for a patient
- * @param db - Firestore instance
- * @param patientId - ID of the patient
- * @param eventId - ID of the event
- */
-export async function deletePatientCalendarEventUtil(
-  db: Firestore,
-  patientId: string,
-  eventId: string
-): Promise<void> {
-  const eventRef = doc(
-    db,
-    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  await deleteDoc(eventRef);
-}
-
-/**
- * Deletes a calendar event for a clinic
- * @param db - Firestore instance
- * @param clinicId - ID of the clinic
- * @param eventId - ID of the event
- */
-export async function deleteClinicCalendarEventUtil(
-  db: Firestore,
-  clinicId: string,
-  eventId: string
-): Promise<void> {
-  const eventRef = doc(
-    db,
-    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
-  );
-  await deleteDoc(eventRef);
-}
-
-/**
- * Searches for calendar events based on specified criteria
- * @param db - Firestore instance
- * @param params - Search parameters
- * @param params.searchLocation - The primary location to search (practitioner, patient, or clinic)
- * @param params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for
- * @param params.clinicId - Optional clinic ID to filter by
- * @param params.practitionerId - Optional practitioner ID to filter by
- * @param params.patientId - Optional patient ID to filter by
- * @param params.procedureId - Optional procedure ID to filter by
- * @param params.dateRange - Optional date range to filter by (event start time)
- * @param params.eventStatus - Optional event status to filter by
- * @param params.eventType - Optional event type to filter by
- * @returns Promise resolving to an array of matching calendar events
- */
-export async function searchCalendarEventsUtil(
-  db: Firestore,
-  params: SearchCalendarEventsParams
-): Promise<CalendarEvent[]> {
-  const { searchLocation, entityId, ...filters } = params;
-
-  let baseCollectionPath: string;
-  const constraints: QueryConstraint[] = [];
-
-  // Determine the base collection and apply initial filter based on searchLocation
-  switch (searchLocation) {
-    case SearchLocationEnum.PRACTITIONER:
-      if (!entityId) {
-        throw new Error(
-          "Practitioner ID (entityId) is required when searching practitioner calendar."
-        );
-      }
-      baseCollectionPath = `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
-      // If practitionerId filter is provided, it must match the entityId for this search location
-      if (filters.practitionerId && filters.practitionerId !== entityId) {
-        console.warn(
-          `Provided practitionerId filter (${filters.practitionerId}) does not match search entityId (${entityId}). Returning empty results.`
-        );
-        return [];
-      }
-      // Ensure we don't add a redundant filter if the caller also specified it
-      filters.practitionerId = undefined;
-      break;
-
-    case SearchLocationEnum.PATIENT:
-      if (!entityId) {
-        throw new Error(
-          "Patient ID (entityId) is required when searching patient calendar."
-        );
-      }
-      baseCollectionPath = `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
-      // If patientId filter is provided, it must match the entityId for this search location
-      if (filters.patientId && filters.patientId !== entityId) {
-        console.warn(
-          `Provided patientId filter (${filters.patientId}) does not match search entityId (${entityId}). Returning empty results.`
-        );
-        return [];
-      }
-      // Ensure we don't add a redundant filter if the caller also specified it
-      filters.patientId = undefined;
-      break;
-
-    case SearchLocationEnum.CLINIC:
-      if (!entityId) {
-        throw new Error(
-          "Clinic ID (entityId) is required when searching clinic-related events."
-        );
-      }
-      // Search the clinic's calendar collection
-      baseCollectionPath = `${CLINICS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
-      constraints.push(where("clinicBranchId", "==", entityId));
-      // If clinicId filter is provided, it must match the entityId for this search location
-      if (filters.clinicId && filters.clinicId !== entityId) {
-        console.warn(
-          `Provided clinicId filter (${filters.clinicId}) does not match search entityId (${entityId}). Returning empty results.`
-        );
-        return [];
-      }
-      // Ensure we don't add a redundant filter if the caller also specified it
-      filters.clinicId = undefined; // Already handled by the base query
-      break;
-
-    default:
-      throw new Error(`Invalid search location: ${searchLocation}`);
-  }
-
-  const collectionRef = collection(db, baseCollectionPath);
-
-  // Apply optional filters
-  if (filters.clinicId) {
-    constraints.push(where("clinicBranchId", "==", filters.clinicId));
-  }
-  if (filters.practitionerId) {
-    constraints.push(
-      where("practitionerProfileId", "==", filters.practitionerId)
-    );
-  }
-  if (filters.patientId) {
-    constraints.push(where("patientProfileId", "==", filters.patientId));
-  }
-  if (filters.procedureId) {
-    constraints.push(where("procedureId", "==", filters.procedureId));
-  }
-  if (filters.eventStatus) {
-    constraints.push(where("status", "==", filters.eventStatus));
-  }
-  if (filters.eventType) {
-    constraints.push(where("eventType", "==", filters.eventType));
-  }
-  if (filters.dateRange) {
-    // Firestore requires range filters on the same field
-    // We query for events that start within or before the date range
-    // Then post-filter to ensure they overlap (eventTime.end > dateRange.start)
-    // To catch events that start before but overlap, we extend the query start backwards
-    const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days for long blocking events
-    const extendedStart = Timestamp.fromMillis(
-      filters.dateRange.start.toMillis() - MAX_EVENT_DURATION_MS
-    );
-    
-    constraints.push(where("eventTime.start", ">=", extendedStart));
-    constraints.push(where("eventTime.start", "<=", filters.dateRange.end));
-    // Note: You might need to order by eventTime.start for range filters to work efficiently
-    // constraints.push(orderBy("eventTime.start"));
-  }
-
-  // Build and execute the query
-  try {
-    const finalQuery = query(collectionRef, ...constraints);
-    const querySnapshot = await getDocs(finalQuery);
-
-    let events = querySnapshot.docs.map(
-      (doc) => ({ id: doc.id, ...doc.data() } as CalendarEvent)
-    );
-
-    // Post-filter to ensure events actually overlap with the date range (if provided)
-    // An event overlaps if: eventTime.start < dateRange.end AND eventTime.end > dateRange.start
-    if (filters.dateRange) {
-      events = events.filter((event) => {
-        const overlaps =
-          event.eventTime.end.toMillis() > filters.dateRange!.start.toMillis();
-        if (!overlaps) {
-          console.debug(
-            `[searchCalendarEventsUtil] Filtered out non-overlapping event:`,
-            {
-              eventId: event.id,
-              eventStart: event.eventTime.start.toDate().toISOString(),
-              eventEnd: event.eventTime.end.toDate().toISOString(),
-              queryStart: filters.dateRange!.start.toDate().toISOString(),
-              queryEnd: filters.dateRange!.end.toDate().toISOString(),
-            }
-          );
-        }
-        return overlaps;
-      });
-    }
-
-    return events;
-  } catch (error) {
-    console.error("Error searching calendar events:", error);
-    // Depending on requirements, you might want to return an empty array or re-throw
-    return [];
-  }
-}
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  setDoc,
+  updateDoc,
+  deleteDoc,
+  query,
+  where,
+  orderBy,
+  Timestamp,
+  serverTimestamp,
+  Firestore,
+  DocumentReference,
+  QueryConstraint,
+} from "firebase/firestore";
+import {
+  CalendarEvent,
+  CalendarEventStatus,
+  CalendarEventTime,
+  CalendarEventType,
+  CalendarSyncStatus,
+  CreateCalendarEventData,
+  UpdateCalendarEventData,
+  CALENDAR_COLLECTION,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
+} from "../../../types/calendar";
+import { PRACTITIONERS_COLLECTION } from "../../../types/practitioner";
+import { PATIENTS_COLLECTION } from "../../../types/patient";
+import { CLINICS_COLLECTION } from "../../../types/clinic";
+
+/**
+ * Creates a calendar event for a practitioner
+ * @param db - Firestore instance
+ * @param practitionerId - ID of the practitioner
+ * @param eventData - Calendar event data
+ * @param generateId - Function to generate a unique ID
+ * @returns Created calendar event
+ */
+export async function createPractitionerCalendarEventUtil(
+  db: Firestore,
+  practitionerId: string,
+  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
+  generateId: () => string
+): Promise<CalendarEvent> {
+  // TODO: Add validation for event data
+  // - Check if practitioner exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+  // - Validate required fields
+
+  const eventId = generateId();
+  const eventRef = doc(
+    db,
+    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const newEvent: CreateCalendarEventData = {
+    id: eventId,
+    ...eventData,
+    createdAt: serverTimestamp(),
+    updatedAt: serverTimestamp(),
+  };
+
+  await setDoc(eventRef, newEvent);
+
+  // Convert server timestamp to Timestamp for return value
+  return {
+    ...newEvent,
+    createdAt: Timestamp.now(),
+    updatedAt: Timestamp.now(),
+  } as CalendarEvent;
+}
+
+/**
+ * Creates a calendar event for a patient
+ * @param db - Firestore instance
+ * @param patientId - ID of the patient
+ * @param eventData - Calendar event data
+ * @param generateId - Function to generate a unique ID
+ * @returns Created calendar event
+ */
+export async function createPatientCalendarEventUtil(
+  db: Firestore,
+  patientId: string,
+  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
+  generateId: () => string
+): Promise<CalendarEvent> {
+  // TODO: Add validation for event data
+  // - Check if patient exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+  // - Validate required fields
+
+  const eventId = generateId();
+  const eventRef = doc(
+    db,
+    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const newEvent: CreateCalendarEventData = {
+    id: eventId,
+    ...eventData,
+    createdAt: serverTimestamp(),
+    updatedAt: serverTimestamp(),
+  };
+
+  await setDoc(eventRef, newEvent);
+
+  // Convert server timestamp to Timestamp for return value
+  return {
+    ...newEvent,
+    createdAt: Timestamp.now(),
+    updatedAt: Timestamp.now(),
+  } as CalendarEvent;
+}
+
+/**
+ * Creates a calendar event for a clinic
+ * @param db - Firestore instance
+ * @param clinicId - ID of the clinic
+ * @param eventData - Calendar event data
+ * @param generateId - Function to generate a unique ID
+ * @returns Created calendar event
+ */
+export async function createClinicCalendarEventUtil(
+  db: Firestore,
+  clinicId: string,
+  eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">,
+  generateId: () => string
+): Promise<CalendarEvent> {
+  // TODO: Add validation for event data
+  // - Check if clinic exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+  // - Validate required fields
+
+  const eventId = generateId();
+  const eventRef = doc(
+    db,
+    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const newEvent: CreateCalendarEventData = {
+    id: eventId,
+    ...eventData,
+    createdAt: serverTimestamp(),
+    updatedAt: serverTimestamp(),
+  };
+
+  await setDoc(eventRef, newEvent);
+
+  // Convert server timestamp to Timestamp for return value
+  return {
+    ...newEvent,
+    createdAt: Timestamp.now(),
+    updatedAt: Timestamp.now(),
+  } as CalendarEvent;
+}
+
+/**
+ * Gets a calendar event for a practitioner
+ * @param db - Firestore instance
+ * @param practitionerId - ID of the practitioner
+ * @param eventId - ID of the event
+ * @returns Calendar event or null if not found
+ */
+export async function getPractitionerCalendarEventUtil(
+  db: Firestore,
+  practitionerId: string,
+  eventId: string
+): Promise<CalendarEvent | null> {
+  const eventRef = doc(
+    db,
+    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  const eventDoc = await getDoc(eventRef);
+
+  if (!eventDoc.exists()) {
+    return null;
+  }
+
+  return eventDoc.data() as CalendarEvent;
+}
+
+/**
+ * Gets a calendar event for a patient
+ * @param db - Firestore instance
+ * @param patientId - ID of the patient
+ * @param eventId - ID of the event
+ * @returns Calendar event or null if not found
+ */
+export async function getPatientCalendarEventUtil(
+  db: Firestore,
+  patientId: string,
+  eventId: string
+): Promise<CalendarEvent | null> {
+  const eventRef = doc(
+    db,
+    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  const eventDoc = await getDoc(eventRef);
+
+  if (!eventDoc.exists()) {
+    return null;
+  }
+
+  return eventDoc.data() as CalendarEvent;
+}
+
+/**
+ * Gets a calendar event for a clinic
+ * @param db - Firestore instance
+ * @param clinicId - ID of the clinic
+ * @param eventId - ID of the event
+ * @returns Calendar event or null if not found
+ */
+export async function getClinicCalendarEventUtil(
+  db: Firestore,
+  clinicId: string,
+  eventId: string
+): Promise<CalendarEvent | null> {
+  const eventRef = doc(
+    db,
+    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  const eventDoc = await getDoc(eventRef);
+
+  if (!eventDoc.exists()) {
+    return null;
+  }
+
+  return eventDoc.data() as CalendarEvent;
+}
+
+/**
+ * Gets calendar events for a practitioner within a date range
+ * @param db - Firestore instance
+ * @param practitionerId - ID of the practitioner
+ * @param startDate - Start date of the range
+ * @param endDate - End date of the range
+ * @returns Array of calendar events
+ */
+export async function getPractitionerCalendarEventsUtil(
+  db: Firestore,
+  practitionerId: string,
+  startDate: Date,
+  endDate: Date
+): Promise<CalendarEvent[]> {
+  const startTimestamp = Timestamp.fromDate(startDate);
+  const endTimestamp = Timestamp.fromDate(endDate);
+
+  const eventsRef = collection(
+    db,
+    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}`
+  );
+
+  const q = query(
+    eventsRef,
+    where("eventTime.start", ">=", startTimestamp),
+    where("eventTime.end", "<=", endTimestamp),
+    orderBy("eventTime.start", "asc")
+  );
+
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
+}
+
+/**
+ * Gets calendar events for a patient within a date range
+ * @param db - Firestore instance
+ * @param patientId - ID of the patient
+ * @param startDate - Start date of the range
+ * @param endDate - End date of the range
+ * @returns Array of calendar events
+ */
+export async function getPatientCalendarEventsUtil(
+  db: Firestore,
+  patientId: string,
+  startDate: Date,
+  endDate: Date
+): Promise<CalendarEvent[]> {
+  const startTimestamp = Timestamp.fromDate(startDate);
+  const endTimestamp = Timestamp.fromDate(endDate);
+
+  const eventsRef = collection(
+    db,
+    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}`
+  );
+
+  const q = query(
+    eventsRef,
+    where("eventTime.start", ">=", startTimestamp),
+    where("eventTime.end", "<=", endTimestamp),
+    orderBy("eventTime.start", "asc")
+  );
+
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
+}
+
+/**
+ * Gets calendar events for a clinic within a date range
+ * @param db - Firestore instance
+ * @param clinicId - ID of the clinic
+ * @param startDate - Start date of the range
+ * @param endDate - End date of the range
+ * @returns Array of calendar events
+ */
+export async function getClinicCalendarEventsUtil(
+  db: Firestore,
+  clinicId: string,
+  startDate: Date,
+  endDate: Date
+): Promise<CalendarEvent[]> {
+  const startTimestamp = Timestamp.fromDate(startDate);
+  const endTimestamp = Timestamp.fromDate(endDate);
+
+  const eventsRef = collection(
+    db,
+    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}`
+  );
+
+  const q = query(
+    eventsRef,
+    where("eventTime.start", ">=", startTimestamp),
+    where("eventTime.end", "<=", endTimestamp),
+    orderBy("eventTime.start", "asc")
+  );
+
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
+}
+
+/**
+ * Updates a calendar event for a practitioner
+ * @param db - Firestore instance
+ * @param practitionerId - ID of the practitioner
+ * @param eventId - ID of the event
+ * @param updateData - Data to update
+ * @returns Updated calendar event
+ */
+export async function updatePractitionerCalendarEventUtil(
+  db: Firestore,
+  practitionerId: string,
+  eventId: string,
+  updateData: Omit<UpdateCalendarEventData, "updatedAt">
+): Promise<CalendarEvent> {
+  // TODO: Add validation for update data
+  // - Check if event exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+
+  const eventRef = doc(
+    db,
+    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const updates: UpdateCalendarEventData = {
+    ...updateData,
+    updatedAt: serverTimestamp(),
+  };
+
+  await updateDoc(eventRef, updates as any);
+
+  // Get the updated document
+  const updatedDoc = await getDoc(eventRef);
+
+  if (!updatedDoc.exists()) {
+    throw new Error("Event not found after update");
+  }
+
+  return updatedDoc.data() as CalendarEvent;
+}
+
+/**
+ * Updates a calendar event for a patient
+ * @param db - Firestore instance
+ * @param patientId - ID of the patient
+ * @param eventId - ID of the event
+ * @param updateData - Data to update
+ * @returns Updated calendar event
+ */
+export async function updatePatientCalendarEventUtil(
+  db: Firestore,
+  patientId: string,
+  eventId: string,
+  updateData: Omit<UpdateCalendarEventData, "updatedAt">
+): Promise<CalendarEvent> {
+  // TODO: Add validation for update data
+  // - Check if event exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+
+  const eventRef = doc(
+    db,
+    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const updates: UpdateCalendarEventData = {
+    ...updateData,
+    updatedAt: serverTimestamp(),
+  };
+
+  await updateDoc(eventRef, updates as any);
+
+  // Get the updated document
+  const updatedDoc = await getDoc(eventRef);
+
+  if (!updatedDoc.exists()) {
+    throw new Error("Event not found after update");
+  }
+
+  return updatedDoc.data() as CalendarEvent;
+}
+
+/**
+ * Updates a calendar event for a clinic
+ * @param db - Firestore instance
+ * @param clinicId - ID of the clinic
+ * @param eventId - ID of the event
+ * @param updateData - Data to update
+ * @returns Updated calendar event
+ */
+export async function updateClinicCalendarEventUtil(
+  db: Firestore,
+  clinicId: string,
+  eventId: string,
+  updateData: Omit<UpdateCalendarEventData, "updatedAt">
+): Promise<CalendarEvent> {
+  // TODO: Add validation for update data
+  // - Check if event exists
+  // - Validate event time (start < end)
+  // - Check for overlapping events
+
+  const eventRef = doc(
+    db,
+    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+
+  const updates: UpdateCalendarEventData = {
+    ...updateData,
+    updatedAt: serverTimestamp(),
+  };
+
+  await updateDoc(eventRef, updates as any);
+
+  // Get the updated document
+  const updatedDoc = await getDoc(eventRef);
+
+  if (!updatedDoc.exists()) {
+    throw new Error("Event not found after update");
+  }
+
+  return updatedDoc.data() as CalendarEvent;
+}
+
+/**
+ * Deletes a calendar event for a practitioner
+ * @param db - Firestore instance
+ * @param practitionerId - ID of the practitioner
+ * @param eventId - ID of the event
+ */
+export async function deletePractitionerCalendarEventUtil(
+  db: Firestore,
+  practitionerId: string,
+  eventId: string
+): Promise<void> {
+  const eventRef = doc(
+    db,
+    `${PRACTITIONERS_COLLECTION}/${practitionerId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  await deleteDoc(eventRef);
+}
+
+/**
+ * Deletes a calendar event for a patient
+ * @param db - Firestore instance
+ * @param patientId - ID of the patient
+ * @param eventId - ID of the event
+ */
+export async function deletePatientCalendarEventUtil(
+  db: Firestore,
+  patientId: string,
+  eventId: string
+): Promise<void> {
+  const eventRef = doc(
+    db,
+    `${PATIENTS_COLLECTION}/${patientId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  await deleteDoc(eventRef);
+}
+
+/**
+ * Deletes a calendar event for a clinic
+ * @param db - Firestore instance
+ * @param clinicId - ID of the clinic
+ * @param eventId - ID of the event
+ */
+export async function deleteClinicCalendarEventUtil(
+  db: Firestore,
+  clinicId: string,
+  eventId: string
+): Promise<void> {
+  const eventRef = doc(
+    db,
+    `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}/${eventId}`
+  );
+  await deleteDoc(eventRef);
+}
+
+/**
+ * Searches for calendar events based on specified criteria
+ * @param db - Firestore instance
+ * @param params - Search parameters
+ * @param params.searchLocation - The primary location to search (practitioner, patient, or clinic)
+ * @param params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for
+ * @param params.clinicId - Optional clinic ID to filter by
+ * @param params.practitionerId - Optional practitioner ID to filter by
+ * @param params.patientId - Optional patient ID to filter by
+ * @param params.procedureId - Optional procedure ID to filter by
+ * @param params.dateRange - Optional date range to filter by (event start time)
+ * @param params.eventStatus - Optional event status to filter by
+ * @param params.eventType - Optional event type to filter by
+ * @returns Promise resolving to an array of matching calendar events
+ */
+export async function searchCalendarEventsUtil(
+  db: Firestore,
+  params: SearchCalendarEventsParams
+): Promise<CalendarEvent[]> {
+  const { searchLocation, entityId, ...filters } = params;
+
+  let baseCollectionPath: string;
+  const constraints: QueryConstraint[] = [];
+
+  // Determine the base collection and apply initial filter based on searchLocation
+  switch (searchLocation) {
+    case SearchLocationEnum.PRACTITIONER:
+      if (!entityId) {
+        throw new Error(
+          "Practitioner ID (entityId) is required when searching practitioner calendar."
+        );
+      }
+      baseCollectionPath = `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+      // If practitionerId filter is provided, it must match the entityId for this search location
+      if (filters.practitionerId && filters.practitionerId !== entityId) {
+        console.warn(
+          `Provided practitionerId filter (${filters.practitionerId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.practitionerId = undefined;
+      break;
+
+    case SearchLocationEnum.PATIENT:
+      if (!entityId) {
+        throw new Error(
+          "Patient ID (entityId) is required when searching patient calendar."
+        );
+      }
+      baseCollectionPath = `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+      // If patientId filter is provided, it must match the entityId for this search location
+      if (filters.patientId && filters.patientId !== entityId) {
+        console.warn(
+          `Provided patientId filter (${filters.patientId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.patientId = undefined;
+      break;
+
+    case SearchLocationEnum.CLINIC:
+      if (!entityId) {
+        throw new Error(
+          "Clinic ID (entityId) is required when searching clinic-related events."
+        );
+      }
+      // Search the clinic's calendar collection
+      baseCollectionPath = `${CLINICS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+      constraints.push(where("clinicBranchId", "==", entityId));
+      // If clinicId filter is provided, it must match the entityId for this search location
+      if (filters.clinicId && filters.clinicId !== entityId) {
+        console.warn(
+          `Provided clinicId filter (${filters.clinicId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.clinicId = undefined; // Already handled by the base query
+      break;
+
+    default:
+      throw new Error(`Invalid search location: ${searchLocation}`);
+  }
+
+  const collectionRef = collection(db, baseCollectionPath);
+
+  // Apply optional filters
+  if (filters.clinicId) {
+    constraints.push(where("clinicBranchId", "==", filters.clinicId));
+  }
+  if (filters.practitionerId) {
+    constraints.push(
+      where("practitionerProfileId", "==", filters.practitionerId)
+    );
+  }
+  if (filters.patientId) {
+    constraints.push(where("patientProfileId", "==", filters.patientId));
+  }
+  if (filters.procedureId) {
+    constraints.push(where("procedureId", "==", filters.procedureId));
+  }
+  if (filters.eventStatus) {
+    constraints.push(where("status", "==", filters.eventStatus));
+  }
+  if (filters.eventType) {
+    constraints.push(where("eventType", "==", filters.eventType));
+  }
+  if (filters.dateRange) {
+    // Firestore requires range filters on the same field
+    // We query for events that start within or before the date range
+    // Then post-filter to ensure they overlap (eventTime.end > dateRange.start)
+    // To catch events that start before but overlap, we extend the query start backwards
+    const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days for long blocking events
+    const extendedStart = Timestamp.fromMillis(
+      filters.dateRange.start.toMillis() - MAX_EVENT_DURATION_MS
+    );
+    
+    constraints.push(where("eventTime.start", ">=", extendedStart));
+    constraints.push(where("eventTime.start", "<=", filters.dateRange.end));
+    // Note: You might need to order by eventTime.start for range filters to work efficiently
+    // constraints.push(orderBy("eventTime.start"));
+  }
+
+  // Build and execute the query
+  try {
+    const finalQuery = query(collectionRef, ...constraints);
+    const querySnapshot = await getDocs(finalQuery);
+
+    let events = querySnapshot.docs.map(
+      (doc) => ({ id: doc.id, ...doc.data() } as CalendarEvent)
+    );
+
+    // Post-filter to ensure events actually overlap with the date range (if provided)
+    // An event overlaps if: eventTime.start < dateRange.end AND eventTime.end > dateRange.start
+    if (filters.dateRange) {
+      events = events.filter((event) => {
+        const overlaps =
+          event.eventTime.end.toMillis() > filters.dateRange!.start.toMillis();
+        if (!overlaps) {
+          console.debug(
+            `[searchCalendarEventsUtil] Filtered out non-overlapping event:`,
+            {
+              eventId: event.id,
+              eventStart: event.eventTime.start.toDate().toISOString(),
+              eventEnd: event.eventTime.end.toDate().toISOString(),
+              queryStart: filters.dateRange!.start.toDate().toISOString(),
+              queryEnd: filters.dateRange!.end.toDate().toISOString(),
+            }
+          );
+        }
+        return overlaps;
+      });
+    }
+
+    return events;
+  } catch (error) {
+    console.error("Error searching calendar events:", error);
+    // Depending on requirements, you might want to return an empty array or re-throw
+    return [];
+  }
+}