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

package/src/services/appointment/utils/appointment.utils.ts

@@ -1,620 +1,620 @@
-import {
-  Firestore,
-  collection,
-  doc,
-  getDoc,
-  getDocs,
-  query,
-  where,
-  setDoc,
-  updateDoc,
-  serverTimestamp,
-  Timestamp,
-  orderBy,
-  limit,
-  startAfter,
-  QueryConstraint,
-  DocumentSnapshot,
-} from 'firebase/firestore';
-import {
-  Appointment,
-  AppointmentStatus,
-  CreateAppointmentData,
-  UpdateAppointmentData,
-  APPOINTMENTS_COLLECTION,
-  SearchAppointmentsParams,
-  PaymentStatus,
-} from '../../../types/appointment';
-import { CalendarEvent, CALENDAR_COLLECTION } from '../../../types/calendar';
-import { ProcedureSummaryInfo } from '../../../types/procedure';
-import { ClinicInfo, PatientProfileInfo, PractitionerProfileInfo } from '../../../types/profile';
-import { PRACTITIONERS_COLLECTION } from '../../../types/practitioner';
-import { PATIENTS_COLLECTION } from '../../../types/patient';
-import { CLINICS_COLLECTION } from '../../../types/clinic';
-import { getSensitiveInfoDocRef } from '../../patient/utils/docs.utils';
-import { BlockingCondition } from '../../../backoffice/types/static/blocking-condition.types';
-import { Requirement } from '../../../backoffice/types/requirement.types';
-import { PROCEDURES_COLLECTION } from '../../../types/procedure';
-import { Technology, TECHNOLOGIES_COLLECTION } from '../../../backoffice/types/technology.types';
-import type { ContraindicationDynamic } from '../../../backoffice';
-
-/**
- * Fetches all the necessary information for an appointment by IDs.
- *
- * @param db Firestore instance
- * @param clinicId Clinic ID
- * @param practitionerId Practitioner ID
- * @param patientId Patient ID
- * @param procedureId Procedure ID
- * @returns Object containing the aggregated information
- */
-export async function fetchAggregatedInfoUtil(
-  db: Firestore,
-  clinicId: string,
-  practitionerId: string,
-  patientId: string,
-  procedureId: string,
-): Promise<{
-  clinicInfo: ClinicInfo;
-  practitionerInfo: PractitionerProfileInfo;
-  patientInfo: PatientProfileInfo;
-  procedureInfo: ProcedureSummaryInfo;
-  blockingConditions: BlockingCondition[];
-  contraindications: ContraindicationDynamic[];
-  preProcedureRequirements: Requirement[];
-  postProcedureRequirements: Requirement[];
-}> {
-  try {
-    // Fetch all data in parallel for efficiency (including patient sensitive-info for PII)
-    const [clinicDoc, practitionerDoc, patientDoc, patientSensitiveDoc, procedureDoc] =
-      await Promise.all([
-        getDoc(doc(db, CLINICS_COLLECTION, clinicId)),
-        getDoc(doc(db, PRACTITIONERS_COLLECTION, practitionerId)),
-        getDoc(doc(db, PATIENTS_COLLECTION, patientId)),
-        getDoc(getSensitiveInfoDocRef(db, patientId)),
-        getDoc(doc(db, PROCEDURES_COLLECTION, procedureId)),
-      ]);
-
-    // Check if all required entities exist
-    if (!clinicDoc.exists()) {
-      throw new Error(`Clinic with ID ${clinicId} not found`);
-    }
-    if (!practitionerDoc.exists()) {
-      throw new Error(`Practitioner with ID ${practitionerId} not found`);
-    }
-    if (!patientDoc.exists()) {
-      throw new Error(`Patient with ID ${patientId} not found`);
-    }
-    if (!procedureDoc.exists()) {
-      throw new Error(`Procedure with ID ${procedureId} not found`);
-    }
-
-    const clinicData = clinicDoc.data();
-    const practitionerData = practitionerDoc.data();
-    const patientData = patientDoc.data();
-    const patientSensitiveData = patientSensitiveDoc.exists()
-      ? (patientSensitiveDoc.data() as { firstName?: string; lastName?: string; email?: string; phoneNumber?: string; dateOfBirth?: any; gender?: string })
-      : null;
-    const procedureData = procedureDoc.data();
-
-    // Extract relevant info for ClinicInfo
-    const clinicInfo: ClinicInfo = {
-      id: clinicId,
-      featuredPhoto: clinicData.featuredPhotos?.[0] || '',
-      name: clinicData.name,
-      description: clinicData.description || null,
-      location: clinicData.location,
-      contactInfo: clinicData.contactInfo,
-    };
-
-    // Extract relevant info for PractitionerProfileInfo
-    const practitionerInfo: PractitionerProfileInfo = {
-      id: practitionerId,
-      practitionerPhoto: practitionerData.basicInfo?.profileImageUrl || null,
-      name: `${practitionerData.basicInfo?.firstName || ''} ${
-        practitionerData.basicInfo?.lastName || ''
-      }`.trim(),
-      email: practitionerData.basicInfo?.email || '',
-      phone: practitionerData.basicInfo?.phoneNumber || null,
-      certification: practitionerData.certification,
-    };
-
-    // Extract relevant info for PatientProfileInfo
-    // Prefer sensitive-info (patient PII) over profile; profile is fallback for displayName from manual creation
-    const patientInfo: PatientProfileInfo = {
-      id: patientId,
-      fullName:
-        patientSensitiveData?.firstName && patientSensitiveData?.lastName
-          ? `${patientSensitiveData.firstName} ${patientSensitiveData.lastName}`.trim()
-          : patientData.displayName || '',
-      email: patientSensitiveData?.email ?? patientData.email ?? '',
-      phone: patientSensitiveData?.phoneNumber ?? patientData.phoneNumber ?? null,
-      dateOfBirth: patientSensitiveData?.dateOfBirth ?? patientData.dateOfBirth ?? Timestamp.now(),
-      gender: patientSensitiveData?.gender ?? patientData.gender ?? 'other',
-    };
-
-    // Extract procedureInfo from the procedure document
-    // Assuming procedureData already has a procedureInfo property or similar structure
-    const procedureInfo: ProcedureSummaryInfo = {
-      id: procedureId,
-      name: procedureData.name,
-      description: procedureData.description,
-      photo: procedureData.photo || '',
-      family: procedureData.family,
-      categoryName: procedureData.category?.name || '',
-      subcategoryName: procedureData.subcategory?.name || '',
-      technologyName: procedureData.technology?.name || '',
-      brandName: procedureData.product?.brandName || '', // Safe: optional chaining
-      productName: procedureData.product?.name || '', // Safe: optional chaining
-      price: procedureData.price || 0,
-      pricingMeasure: procedureData.pricingMeasure,
-      currency: procedureData.currency,
-      duration: procedureData.duration || 0,
-      clinicId: clinicId,
-      clinicName: clinicInfo.name,
-      practitionerId: practitionerId,
-      practitionerName: practitionerInfo.name,
-    };
-
-    // Fetch the technology document to get procedure requirements
-    let technologyId = '';
-    if (procedureData.technology?.id) {
-      technologyId = procedureData.technology.id;
-    }
-
-    let blockingConditions: BlockingCondition[] = [];
-    let contraindications: ContraindicationDynamic[] = [];
-    let preProcedureRequirements: Requirement[] = [];
-    let postProcedureRequirements: Requirement[] = [];
-
-    // If we have a technology ID, fetch its details
-    if (technologyId) {
-      const technologyDoc = await getDoc(doc(db, TECHNOLOGIES_COLLECTION, technologyId));
-      if (technologyDoc.exists()) {
-        const technologyData = technologyDoc.data() as Technology;
-
-        // Extract technology-related info
-        blockingConditions = technologyData.blockingConditions || [];
-        contraindications = technologyData.contraindications || [];
-        preProcedureRequirements = technologyData.requirements?.pre || [];
-        postProcedureRequirements = technologyData.requirements?.post || [];
-      }
-    } else {
-      // Fallback to procedure-level data if technology not available
-      blockingConditions = procedureData.blockingConditions || [];
-      contraindications = procedureData.contraindications || [];
-      preProcedureRequirements = procedureData.preRequirements || [];
-      postProcedureRequirements = procedureData.postRequirements || [];
-    }
-
-    return {
-      clinicInfo,
-      practitionerInfo,
-      patientInfo,
-      procedureInfo,
-      blockingConditions,
-      contraindications,
-      preProcedureRequirements,
-      postProcedureRequirements,
-    };
-  } catch (error) {
-    console.error('Error fetching aggregated info:', error);
-    throw error;
-  }
-}
-
-/**
- * Creates a new appointment in Firestore.
- *
- * @param db Firestore instance
- * @param data Data needed to create the appointment
- * @param aggregatedInfo Already fetched and aggregated info
- * @param generateId Function to generate a unique ID
- * @returns The created Appointment
- */
-// export async function createAppointmentUtil(
-//   db: Firestore,
-//   data: CreateAppointmentData,
-//   aggregatedInfo: {
-//     clinicInfo: ClinicInfo;
-//     practitionerInfo: PractitionerProfileInfo;
-//     patientInfo: PatientProfileInfo;
-//     procedureInfo: ProcedureSummaryInfo;
-//     blockingConditions: BlockingCondition[];
-//     contraindications: ContraindicationDynamic[];
-//     preProcedureRequirements: Requirement[];
-//     postProcedureRequirements: Requirement[];
-//   },
-//   generateId: () => string
-// ): Promise<Appointment> {
-//   try {
-//     const appointmentId = generateId();
-
-//     // Create appointment object
-//     const appointment: Omit<Appointment, "createdAt" | "updatedAt"> & {
-//       createdAt: any;
-//       updatedAt: any;
-//     } = {
-//       id: appointmentId,
-//       calendarEventId: data.calendarEventId,
-//       clinicBranchId: data.clinicBranchId,
-//       clinicInfo: aggregatedInfo.clinicInfo,
-//       practitionerId: data.practitionerId,
-//       practitionerInfo: aggregatedInfo.practitionerInfo,
-//       patientId: data.patientId,
-//       patientInfo: aggregatedInfo.patientInfo,
-//       procedureId: data.procedureId,
-//       procedureInfo: aggregatedInfo.procedureInfo,
-//       status: data.initialStatus,
-//       bookingTime: Timestamp.now(),
-//       appointmentStartTime: data.appointmentStartTime,
-//       appointmentEndTime: data.appointmentEndTime,
-//       patientNotes: data.patientNotes || null,
-//       cost: data.cost,
-//       currency: data.currency,
-//       paymentStatus: data.initialPaymentStatus || PaymentStatus.UNPAID,
-//       blockingConditions: aggregatedInfo.blockingConditions,
-//       contraindications: aggregatedInfo.contraindications,
-//       preProcedureRequirements: aggregatedInfo.preProcedureRequirements,
-//       postProcedureRequirements: aggregatedInfo.postProcedureRequirements,
-//       completedPreRequirements: [],
-//       completedPostRequirements: [],
-//       createdAt: serverTimestamp(),
-//       updatedAt: serverTimestamp(),
-//     };
-
-//     // Add additional fields for confirmation if appointment is already confirmed
-//     if (data.initialStatus === AppointmentStatus.CONFIRMED) {
-//       appointment.confirmationTime = Timestamp.now();
-//     }
-
-//     // Save to Firestore
-//     await setDoc(doc(db, APPOINTMENTS_COLLECTION, appointmentId), appointment);
-
-//     // Update the calendar event with the appointment ID
-//     const calendarEventRef = doc(db, CALENDAR_COLLECTION, data.calendarEventId);
-//     await updateDoc(calendarEventRef, {
-//       appointmentId: appointmentId,
-//       updatedAt: serverTimestamp(),
-//     });
-
-//     // Return the created appointment
-//     // Convert serverTimestamp to regular Timestamp for immediate use
-//     const now = Timestamp.now();
-//     return {
-//       ...appointment,
-//       createdAt: now,
-//       updatedAt: now,
-//     } as Appointment;
-//   } catch (error) {
-//     console.error("Error creating appointment:", error);
-//     throw error;
-//   }
-// }
-
-/**
- * Updates an existing appointment in Firestore.
- *
- * @param db Firestore instance
- * @param appointmentId ID of the appointment to update
- * @param data Update data for the appointment
- * @returns The updated Appointment
- */
-export async function updateAppointmentUtil(
-  db: Firestore,
-  appointmentId: string,
-  data: UpdateAppointmentData,
-): Promise<Appointment> {
-  try {
-    const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
-    const appointmentDoc = await getDoc(appointmentRef);
-
-    if (!appointmentDoc.exists()) {
-      throw new Error(`Appointment with ID ${appointmentId} not found`);
-    }
-
-    const currentAppointment = appointmentDoc.data() as Appointment;
-
-    // Handle requirement completion tracking
-    let completedPreRequirements = currentAppointment.completedPreRequirements || [];
-    let completedPostRequirements = currentAppointment.completedPostRequirements || [];
-
-    if (data.completedPreRequirements) {
-      // Validate that all IDs exist in the pre-requirements
-      const validPreReqIds = currentAppointment.preProcedureRequirements.map(req => req.id);
-
-      // Only perform validation and merging if the input is an array
-      if (Array.isArray(data.completedPreRequirements)) {
-        const invalidPreReqIds = data.completedPreRequirements.filter(
-          id => !validPreReqIds.includes(id),
-        );
-
-        if (invalidPreReqIds.length > 0) {
-          throw new Error(`Invalid pre-requirement IDs: ${invalidPreReqIds.join(', ')}`);
-        }
-
-        // Update the completed pre-requirements
-        completedPreRequirements = [
-          ...new Set([...completedPreRequirements, ...data.completedPreRequirements]),
-        ];
-      }
-    }
-
-    if (data.completedPostRequirements) {
-      // Validate that all IDs exist in the post-requirements
-      const validPostReqIds = currentAppointment.postProcedureRequirements.map(req => req.id);
-
-      if (Array.isArray(data.completedPostRequirements)) {
-        const invalidPostReqIds = data.completedPostRequirements.filter(
-          id => !validPostReqIds.includes(id),
-        );
-
-        if (invalidPostReqIds.length > 0) {
-          throw new Error(`Invalid post-requirement IDs: ${invalidPostReqIds.join(', ')}`);
-        }
-
-        // Update the completed post-requirements
-        completedPostRequirements = [
-          ...new Set([...completedPostRequirements, ...data.completedPostRequirements]),
-        ];
-      }
-    }
-
-    // Prepare update data
-    const updateData: any = {
-      ...data,
-      completedPreRequirements: Array.isArray(data.completedPreRequirements)
-        ? completedPreRequirements
-        : data.completedPreRequirements,
-      completedPostRequirements: Array.isArray(data.completedPostRequirements)
-        ? completedPostRequirements
-        : data.completedPostRequirements,
-      updatedAt: serverTimestamp(),
-    };
-
-    // Remove undefined fields
-    Object.keys(updateData).forEach(key => {
-      if (updateData[key] === undefined) {
-        delete updateData[key];
-      }
-    });
-
-    // Handle status changes
-    if (data.status && data.status !== currentAppointment.status) {
-      // Handle confirmation
-      if (data.status === AppointmentStatus.CONFIRMED && !updateData.confirmationTime) {
-        updateData.confirmationTime = Timestamp.now();
-      }
-
-      // Update the related calendar event status if needed
-      if (currentAppointment.calendarEventId) {
-        await updateCalendarEventStatus(db, currentAppointment, data.status);
-      }
-    }
-
-    // Update the appointment
-    await updateDoc(appointmentRef, updateData);
-
-    // Fetch the updated appointment
-    const updatedAppointmentDoc = await getDoc(appointmentRef);
-    if (!updatedAppointmentDoc.exists()) {
-      throw new Error(`Failed to retrieve updated appointment ${appointmentId}`);
-    }
-
-    return updatedAppointmentDoc.data() as Appointment;
-  } catch (error) {
-    console.error(`Error updating appointment ${appointmentId}:`, error);
-    throw error;
-  }
-}
-
-/**
- * Updates the status of calendar events across all collections (practitioner, patient, clinic)
- * based on appointment status changes.
- *
- * @param db Firestore instance
- * @param appointment The appointment object containing calendar event references
- * @param appointmentStatus New appointment status
- */
-async function updateCalendarEventStatus(
-  db: Firestore,
-  appointment: Appointment,
-  appointmentStatus: AppointmentStatus,
-): Promise<void> {
-  try {
-    const calendarEventId = appointment.calendarEventId;
-    if (!calendarEventId) {
-      console.warn(`Appointment ${appointment.id} has no calendarEventId, skipping calendar event update`);
-      return;
-    }
-
-    // Map appointment status to calendar event status
-    let calendarStatus: string;
-    switch (appointmentStatus) {
-      case AppointmentStatus.PENDING:
-        calendarStatus = 'pending';
-        break;
-      case AppointmentStatus.CONFIRMED:
-        calendarStatus = 'confirmed';
-        break;
-      case AppointmentStatus.CHECKED_IN:
-        calendarStatus = 'checked_in';
-        break;
-      case AppointmentStatus.IN_PROGRESS:
-        calendarStatus = 'in_progress';
-        break;
-      case AppointmentStatus.CANCELED_PATIENT:
-      case AppointmentStatus.CANCELED_CLINIC:
-      case AppointmentStatus.CANCELED_PATIENT_RESCHEDULED:
-        calendarStatus = 'canceled';
-        break;
-      case AppointmentStatus.RESCHEDULED_BY_CLINIC:
-        calendarStatus = 'rescheduled';
-        break;
-      case AppointmentStatus.COMPLETED:
-        calendarStatus = 'completed';
-        break;
-      case AppointmentStatus.NO_SHOW:
-        calendarStatus = 'no_show';
-        break;
-      default:
-        // For unknown states, don't update the calendar status
-        console.warn(`Unknown appointment status: ${appointmentStatus}, not updating calendar event`);
-        return;
-    }
-
-    const updateData = {
-      status: calendarStatus,
-      updatedAt: serverTimestamp(),
-    };
-
-    // Update all three calendar event collections in parallel
-    const updatePromises: Promise<void>[] = [];
-
-    // Update practitioner calendar event
-    if (appointment.practitionerId) {
-      const practitionerEventRef = doc(
-        db,
-        `${PRACTITIONERS_COLLECTION}/${appointment.practitionerId}/${CALENDAR_COLLECTION}/${calendarEventId}`
-      );
-      updatePromises.push(
-        updateDoc(practitionerEventRef, updateData).catch(error => {
-          console.error(`Error updating practitioner calendar event ${calendarEventId}:`, error);
-        })
-      );
-    }
-
-    // Update patient calendar event
-    if (appointment.patientId) {
-      const patientEventRef = doc(
-        db,
-        `${PATIENTS_COLLECTION}/${appointment.patientId}/${CALENDAR_COLLECTION}/${calendarEventId}`
-      );
-      updatePromises.push(
-        updateDoc(patientEventRef, updateData).catch(error => {
-          console.error(`Error updating patient calendar event ${calendarEventId}:`, error);
-        })
-      );
-    }
-
-    // Update clinic calendar event
-    if (appointment.clinicBranchId) {
-      const clinicEventRef = doc(
-        db,
-        `${CLINICS_COLLECTION}/${appointment.clinicBranchId}/${CALENDAR_COLLECTION}/${calendarEventId}`
-      );
-      updatePromises.push(
-        updateDoc(clinicEventRef, updateData).catch(error => {
-          console.error(`Error updating clinic calendar event ${calendarEventId}:`, error);
-        })
-      );
-    }
-
-    // Wait for all updates to complete
-    await Promise.all(updatePromises);
-    console.log(`Successfully updated calendar event ${calendarEventId} status to ${calendarStatus} across all collections`);
-  } catch (error) {
-    console.error(`Error updating calendar events for appointment ${appointment.id}:`, error);
-    // Don't throw error to avoid failing the appointment update
-  }
-}
-
-/**
- * Gets an appointment by its ID.
- *
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @returns The appointment or null if not found
- */
-export async function getAppointmentByIdUtil(
-  db: Firestore,
-  appointmentId: string,
-): Promise<Appointment | null> {
-  try {
-    const appointmentDoc = await getDoc(doc(db, APPOINTMENTS_COLLECTION, appointmentId));
-
-    if (!appointmentDoc.exists()) {
-      return null;
-    }
-
-    return appointmentDoc.data() as Appointment;
-  } catch (error) {
-    console.error(`Error getting appointment ${appointmentId}:`, error);
-    throw error;
-  }
-}
-
-/**
- * Searches for appointments based on various criteria.
- *
- * @param db Firestore instance
- * @param params Search parameters
- * @returns Found appointments and the last document for pagination
- */
-export async function searchAppointmentsUtil(
-  db: Firestore,
-  params: SearchAppointmentsParams,
-): Promise<{ appointments: Appointment[]; lastDoc: DocumentSnapshot | null }> {
-  try {
-    const constraints: QueryConstraint[] = [];
-
-    // Add filters based on provided params
-    if (params.patientId) {
-      constraints.push(where('patientId', '==', params.patientId));
-    }
-
-    if (params.practitionerId) {
-      constraints.push(where('practitionerId', '==', params.practitionerId));
-    }
-
-    if (params.clinicBranchId) {
-      constraints.push(where('clinicBranchId', '==', params.clinicBranchId));
-    }
-
-    if (params.startDate) {
-      constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(params.startDate)));
-    }
-
-    if (params.endDate) {
-      constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(params.endDate)));
-    }
-
-    if (params.status) {
-      if (Array.isArray(params.status)) {
-        // If multiple statuses, use in operator
-        constraints.push(where('status', 'in', params.status));
-      } else {
-        // Single status
-        constraints.push(where('status', '==', params.status));
-      }
-    }
-
-    // Add ordering
-    constraints.push(orderBy('appointmentStartTime', 'asc'));
-
-    // Add pagination if specified
-    if (params.limit) {
-      constraints.push(limit(params.limit));
-    }
-
-    if (params.startAfter) {
-      constraints.push(startAfter(params.startAfter));
-    }
-
-    // Execute query
-    const q = query(collection(db, APPOINTMENTS_COLLECTION), ...constraints);
-    const querySnapshot = await getDocs(q);
-
-    // Extract results
-    const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
-
-    // Get last document for pagination
-    const lastDoc =
-      querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
-
-    return { appointments, lastDoc };
-  } catch (error) {
-    console.error('Error searching appointments:', error);
-    throw error;
-  }
-}
+import {
+  Firestore,
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  query,
+  where,
+  setDoc,
+  updateDoc,
+  serverTimestamp,
+  Timestamp,
+  orderBy,
+  limit,
+  startAfter,
+  QueryConstraint,
+  DocumentSnapshot,
+} from 'firebase/firestore';
+import {
+  Appointment,
+  AppointmentStatus,
+  CreateAppointmentData,
+  UpdateAppointmentData,
+  APPOINTMENTS_COLLECTION,
+  SearchAppointmentsParams,
+  PaymentStatus,
+} from '../../../types/appointment';
+import { CalendarEvent, CALENDAR_COLLECTION } from '../../../types/calendar';
+import { ProcedureSummaryInfo } from '../../../types/procedure';
+import { ClinicInfo, PatientProfileInfo, PractitionerProfileInfo } from '../../../types/profile';
+import { PRACTITIONERS_COLLECTION } from '../../../types/practitioner';
+import { PATIENTS_COLLECTION } from '../../../types/patient';
+import { CLINICS_COLLECTION } from '../../../types/clinic';
+import { getSensitiveInfoDocRef } from '../../patient/utils/docs.utils';
+import { BlockingCondition } from '../../../backoffice/types/static/blocking-condition.types';
+import { Requirement } from '../../../backoffice/types/requirement.types';
+import { PROCEDURES_COLLECTION } from '../../../types/procedure';
+import { Technology, TECHNOLOGIES_COLLECTION } from '../../../backoffice/types/technology.types';
+import type { ContraindicationDynamic } from '../../../backoffice';
+
+/**
+ * Fetches all the necessary information for an appointment by IDs.
+ *
+ * @param db Firestore instance
+ * @param clinicId Clinic ID
+ * @param practitionerId Practitioner ID
+ * @param patientId Patient ID
+ * @param procedureId Procedure ID
+ * @returns Object containing the aggregated information
+ */
+export async function fetchAggregatedInfoUtil(
+  db: Firestore,
+  clinicId: string,
+  practitionerId: string,
+  patientId: string,
+  procedureId: string,
+): Promise<{
+  clinicInfo: ClinicInfo;
+  practitionerInfo: PractitionerProfileInfo;
+  patientInfo: PatientProfileInfo;
+  procedureInfo: ProcedureSummaryInfo;
+  blockingConditions: BlockingCondition[];
+  contraindications: ContraindicationDynamic[];
+  preProcedureRequirements: Requirement[];
+  postProcedureRequirements: Requirement[];
+}> {
+  try {
+    // Fetch all data in parallel for efficiency (including patient sensitive-info for PII)
+    const [clinicDoc, practitionerDoc, patientDoc, patientSensitiveDoc, procedureDoc] =
+      await Promise.all([
+        getDoc(doc(db, CLINICS_COLLECTION, clinicId)),
+        getDoc(doc(db, PRACTITIONERS_COLLECTION, practitionerId)),
+        getDoc(doc(db, PATIENTS_COLLECTION, patientId)),
+        getDoc(getSensitiveInfoDocRef(db, patientId)),
+        getDoc(doc(db, PROCEDURES_COLLECTION, procedureId)),
+      ]);
+
+    // Check if all required entities exist
+    if (!clinicDoc.exists()) {
+      throw new Error(`Clinic with ID ${clinicId} not found`);
+    }
+    if (!practitionerDoc.exists()) {
+      throw new Error(`Practitioner with ID ${practitionerId} not found`);
+    }
+    if (!patientDoc.exists()) {
+      throw new Error(`Patient with ID ${patientId} not found`);
+    }
+    if (!procedureDoc.exists()) {
+      throw new Error(`Procedure with ID ${procedureId} not found`);
+    }
+
+    const clinicData = clinicDoc.data();
+    const practitionerData = practitionerDoc.data();
+    const patientData = patientDoc.data();
+    const patientSensitiveData = patientSensitiveDoc.exists()
+      ? (patientSensitiveDoc.data() as { firstName?: string; lastName?: string; email?: string; phoneNumber?: string; dateOfBirth?: any; gender?: string })
+      : null;
+    const procedureData = procedureDoc.data();
+
+    // Extract relevant info for ClinicInfo
+    const clinicInfo: ClinicInfo = {
+      id: clinicId,
+      featuredPhoto: clinicData.featuredPhotos?.[0] || '',
+      name: clinicData.name,
+      description: clinicData.description || null,
+      location: clinicData.location,
+      contactInfo: clinicData.contactInfo,
+    };
+
+    // Extract relevant info for PractitionerProfileInfo
+    const practitionerInfo: PractitionerProfileInfo = {
+      id: practitionerId,
+      practitionerPhoto: practitionerData.basicInfo?.profileImageUrl || null,
+      name: `${practitionerData.basicInfo?.firstName || ''} ${
+        practitionerData.basicInfo?.lastName || ''
+      }`.trim(),
+      email: practitionerData.basicInfo?.email || '',
+      phone: practitionerData.basicInfo?.phoneNumber || null,
+      certification: practitionerData.certification,
+    };
+
+    // Extract relevant info for PatientProfileInfo
+    // Prefer sensitive-info (patient PII) over profile; profile is fallback for displayName from manual creation
+    const patientInfo: PatientProfileInfo = {
+      id: patientId,
+      fullName:
+        patientSensitiveData?.firstName && patientSensitiveData?.lastName
+          ? `${patientSensitiveData.firstName} ${patientSensitiveData.lastName}`.trim()
+          : patientData.displayName || '',
+      email: patientSensitiveData?.email ?? patientData.email ?? '',
+      phone: patientSensitiveData?.phoneNumber ?? patientData.phoneNumber ?? null,
+      dateOfBirth: patientSensitiveData?.dateOfBirth ?? patientData.dateOfBirth ?? Timestamp.now(),
+      gender: patientSensitiveData?.gender ?? patientData.gender ?? 'other',
+    };
+
+    // Extract procedureInfo from the procedure document
+    // Assuming procedureData already has a procedureInfo property or similar structure
+    const procedureInfo: ProcedureSummaryInfo = {
+      id: procedureId,
+      name: procedureData.name,
+      description: procedureData.description,
+      photo: procedureData.photo || '',
+      family: procedureData.family,
+      categoryName: procedureData.category?.name || '',
+      subcategoryName: procedureData.subcategory?.name || '',
+      technologyName: procedureData.technology?.name || '',
+      brandName: procedureData.product?.brandName || '', // Safe: optional chaining
+      productName: procedureData.product?.name || '', // Safe: optional chaining
+      price: procedureData.price || 0,
+      pricingMeasure: procedureData.pricingMeasure,
+      currency: procedureData.currency,
+      duration: procedureData.duration || 0,
+      clinicId: clinicId,
+      clinicName: clinicInfo.name,
+      practitionerId: practitionerId,
+      practitionerName: practitionerInfo.name,
+    };
+
+    // Fetch the technology document to get procedure requirements
+    let technologyId = '';
+    if (procedureData.technology?.id) {
+      technologyId = procedureData.technology.id;
+    }
+
+    let blockingConditions: BlockingCondition[] = [];
+    let contraindications: ContraindicationDynamic[] = [];
+    let preProcedureRequirements: Requirement[] = [];
+    let postProcedureRequirements: Requirement[] = [];
+
+    // If we have a technology ID, fetch its details
+    if (technologyId) {
+      const technologyDoc = await getDoc(doc(db, TECHNOLOGIES_COLLECTION, technologyId));
+      if (technologyDoc.exists()) {
+        const technologyData = technologyDoc.data() as Technology;
+
+        // Extract technology-related info
+        blockingConditions = technologyData.blockingConditions || [];
+        contraindications = technologyData.contraindications || [];
+        preProcedureRequirements = technologyData.requirements?.pre || [];
+        postProcedureRequirements = technologyData.requirements?.post || [];
+      }
+    } else {
+      // Fallback to procedure-level data if technology not available
+      blockingConditions = procedureData.blockingConditions || [];
+      contraindications = procedureData.contraindications || [];
+      preProcedureRequirements = procedureData.preRequirements || [];
+      postProcedureRequirements = procedureData.postRequirements || [];
+    }
+
+    return {
+      clinicInfo,
+      practitionerInfo,
+      patientInfo,
+      procedureInfo,
+      blockingConditions,
+      contraindications,
+      preProcedureRequirements,
+      postProcedureRequirements,
+    };
+  } catch (error) {
+    console.error('Error fetching aggregated info:', error);
+    throw error;
+  }
+}
+
+/**
+ * Creates a new appointment in Firestore.
+ *
+ * @param db Firestore instance
+ * @param data Data needed to create the appointment
+ * @param aggregatedInfo Already fetched and aggregated info
+ * @param generateId Function to generate a unique ID
+ * @returns The created Appointment
+ */
+// export async function createAppointmentUtil(
+//   db: Firestore,
+//   data: CreateAppointmentData,
+//   aggregatedInfo: {
+//     clinicInfo: ClinicInfo;
+//     practitionerInfo: PractitionerProfileInfo;
+//     patientInfo: PatientProfileInfo;
+//     procedureInfo: ProcedureSummaryInfo;
+//     blockingConditions: BlockingCondition[];
+//     contraindications: ContraindicationDynamic[];
+//     preProcedureRequirements: Requirement[];
+//     postProcedureRequirements: Requirement[];
+//   },
+//   generateId: () => string
+// ): Promise<Appointment> {
+//   try {
+//     const appointmentId = generateId();
+
+//     // Create appointment object
+//     const appointment: Omit<Appointment, "createdAt" | "updatedAt"> & {
+//       createdAt: any;
+//       updatedAt: any;
+//     } = {
+//       id: appointmentId,
+//       calendarEventId: data.calendarEventId,
+//       clinicBranchId: data.clinicBranchId,
+//       clinicInfo: aggregatedInfo.clinicInfo,
+//       practitionerId: data.practitionerId,
+//       practitionerInfo: aggregatedInfo.practitionerInfo,
+//       patientId: data.patientId,
+//       patientInfo: aggregatedInfo.patientInfo,
+//       procedureId: data.procedureId,
+//       procedureInfo: aggregatedInfo.procedureInfo,
+//       status: data.initialStatus,
+//       bookingTime: Timestamp.now(),
+//       appointmentStartTime: data.appointmentStartTime,
+//       appointmentEndTime: data.appointmentEndTime,
+//       patientNotes: data.patientNotes || null,
+//       cost: data.cost,
+//       currency: data.currency,
+//       paymentStatus: data.initialPaymentStatus || PaymentStatus.UNPAID,
+//       blockingConditions: aggregatedInfo.blockingConditions,
+//       contraindications: aggregatedInfo.contraindications,
+//       preProcedureRequirements: aggregatedInfo.preProcedureRequirements,
+//       postProcedureRequirements: aggregatedInfo.postProcedureRequirements,
+//       completedPreRequirements: [],
+//       completedPostRequirements: [],
+//       createdAt: serverTimestamp(),
+//       updatedAt: serverTimestamp(),
+//     };
+
+//     // Add additional fields for confirmation if appointment is already confirmed
+//     if (data.initialStatus === AppointmentStatus.CONFIRMED) {
+//       appointment.confirmationTime = Timestamp.now();
+//     }
+
+//     // Save to Firestore
+//     await setDoc(doc(db, APPOINTMENTS_COLLECTION, appointmentId), appointment);
+
+//     // Update the calendar event with the appointment ID
+//     const calendarEventRef = doc(db, CALENDAR_COLLECTION, data.calendarEventId);
+//     await updateDoc(calendarEventRef, {
+//       appointmentId: appointmentId,
+//       updatedAt: serverTimestamp(),
+//     });
+
+//     // Return the created appointment
+//     // Convert serverTimestamp to regular Timestamp for immediate use
+//     const now = Timestamp.now();
+//     return {
+//       ...appointment,
+//       createdAt: now,
+//       updatedAt: now,
+//     } as Appointment;
+//   } catch (error) {
+//     console.error("Error creating appointment:", error);
+//     throw error;
+//   }
+// }
+
+/**
+ * Updates an existing appointment in Firestore.
+ *
+ * @param db Firestore instance
+ * @param appointmentId ID of the appointment to update
+ * @param data Update data for the appointment
+ * @returns The updated Appointment
+ */
+export async function updateAppointmentUtil(
+  db: Firestore,
+  appointmentId: string,
+  data: UpdateAppointmentData,
+): Promise<Appointment> {
+  try {
+    const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
+    const appointmentDoc = await getDoc(appointmentRef);
+
+    if (!appointmentDoc.exists()) {
+      throw new Error(`Appointment with ID ${appointmentId} not found`);
+    }
+
+    const currentAppointment = appointmentDoc.data() as Appointment;
+
+    // Handle requirement completion tracking
+    let completedPreRequirements = currentAppointment.completedPreRequirements || [];
+    let completedPostRequirements = currentAppointment.completedPostRequirements || [];
+
+    if (data.completedPreRequirements) {
+      // Validate that all IDs exist in the pre-requirements
+      const validPreReqIds = currentAppointment.preProcedureRequirements.map(req => req.id);
+
+      // Only perform validation and merging if the input is an array
+      if (Array.isArray(data.completedPreRequirements)) {
+        const invalidPreReqIds = data.completedPreRequirements.filter(
+          id => !validPreReqIds.includes(id),
+        );
+
+        if (invalidPreReqIds.length > 0) {
+          throw new Error(`Invalid pre-requirement IDs: ${invalidPreReqIds.join(', ')}`);
+        }
+
+        // Update the completed pre-requirements
+        completedPreRequirements = [
+          ...new Set([...completedPreRequirements, ...data.completedPreRequirements]),
+        ];
+      }
+    }
+
+    if (data.completedPostRequirements) {
+      // Validate that all IDs exist in the post-requirements
+      const validPostReqIds = currentAppointment.postProcedureRequirements.map(req => req.id);
+
+      if (Array.isArray(data.completedPostRequirements)) {
+        const invalidPostReqIds = data.completedPostRequirements.filter(
+          id => !validPostReqIds.includes(id),
+        );
+
+        if (invalidPostReqIds.length > 0) {
+          throw new Error(`Invalid post-requirement IDs: ${invalidPostReqIds.join(', ')}`);
+        }
+
+        // Update the completed post-requirements
+        completedPostRequirements = [
+          ...new Set([...completedPostRequirements, ...data.completedPostRequirements]),
+        ];
+      }
+    }
+
+    // Prepare update data
+    const updateData: any = {
+      ...data,
+      completedPreRequirements: Array.isArray(data.completedPreRequirements)
+        ? completedPreRequirements
+        : data.completedPreRequirements,
+      completedPostRequirements: Array.isArray(data.completedPostRequirements)
+        ? completedPostRequirements
+        : data.completedPostRequirements,
+      updatedAt: serverTimestamp(),
+    };
+
+    // Remove undefined fields
+    Object.keys(updateData).forEach(key => {
+      if (updateData[key] === undefined) {
+        delete updateData[key];
+      }
+    });
+
+    // Handle status changes
+    if (data.status && data.status !== currentAppointment.status) {
+      // Handle confirmation
+      if (data.status === AppointmentStatus.CONFIRMED && !updateData.confirmationTime) {
+        updateData.confirmationTime = Timestamp.now();
+      }
+
+      // Update the related calendar event status if needed
+      if (currentAppointment.calendarEventId) {
+        await updateCalendarEventStatus(db, currentAppointment, data.status);
+      }
+    }
+
+    // Update the appointment
+    await updateDoc(appointmentRef, updateData);
+
+    // Fetch the updated appointment
+    const updatedAppointmentDoc = await getDoc(appointmentRef);
+    if (!updatedAppointmentDoc.exists()) {
+      throw new Error(`Failed to retrieve updated appointment ${appointmentId}`);
+    }
+
+    return updatedAppointmentDoc.data() as Appointment;
+  } catch (error) {
+    console.error(`Error updating appointment ${appointmentId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Updates the status of calendar events across all collections (practitioner, patient, clinic)
+ * based on appointment status changes.
+ *
+ * @param db Firestore instance
+ * @param appointment The appointment object containing calendar event references
+ * @param appointmentStatus New appointment status
+ */
+async function updateCalendarEventStatus(
+  db: Firestore,
+  appointment: Appointment,
+  appointmentStatus: AppointmentStatus,
+): Promise<void> {
+  try {
+    const calendarEventId = appointment.calendarEventId;
+    if (!calendarEventId) {
+      console.warn(`Appointment ${appointment.id} has no calendarEventId, skipping calendar event update`);
+      return;
+    }
+
+    // Map appointment status to calendar event status
+    let calendarStatus: string;
+    switch (appointmentStatus) {
+      case AppointmentStatus.PENDING:
+        calendarStatus = 'pending';
+        break;
+      case AppointmentStatus.CONFIRMED:
+        calendarStatus = 'confirmed';
+        break;
+      case AppointmentStatus.CHECKED_IN:
+        calendarStatus = 'checked_in';
+        break;
+      case AppointmentStatus.IN_PROGRESS:
+        calendarStatus = 'in_progress';
+        break;
+      case AppointmentStatus.CANCELED_PATIENT:
+      case AppointmentStatus.CANCELED_CLINIC:
+      case AppointmentStatus.CANCELED_PATIENT_RESCHEDULED:
+        calendarStatus = 'canceled';
+        break;
+      case AppointmentStatus.RESCHEDULED_BY_CLINIC:
+        calendarStatus = 'rescheduled';
+        break;
+      case AppointmentStatus.COMPLETED:
+        calendarStatus = 'completed';
+        break;
+      case AppointmentStatus.NO_SHOW:
+        calendarStatus = 'no_show';
+        break;
+      default:
+        // For unknown states, don't update the calendar status
+        console.warn(`Unknown appointment status: ${appointmentStatus}, not updating calendar event`);
+        return;
+    }
+
+    const updateData = {
+      status: calendarStatus,
+      updatedAt: serverTimestamp(),
+    };
+
+    // Update all three calendar event collections in parallel
+    const updatePromises: Promise<void>[] = [];
+
+    // Update practitioner calendar event
+    if (appointment.practitionerId) {
+      const practitionerEventRef = doc(
+        db,
+        `${PRACTITIONERS_COLLECTION}/${appointment.practitionerId}/${CALENDAR_COLLECTION}/${calendarEventId}`
+      );
+      updatePromises.push(
+        updateDoc(practitionerEventRef, updateData).catch(error => {
+          console.error(`Error updating practitioner calendar event ${calendarEventId}:`, error);
+        })
+      );
+    }
+
+    // Update patient calendar event
+    if (appointment.patientId) {
+      const patientEventRef = doc(
+        db,
+        `${PATIENTS_COLLECTION}/${appointment.patientId}/${CALENDAR_COLLECTION}/${calendarEventId}`
+      );
+      updatePromises.push(
+        updateDoc(patientEventRef, updateData).catch(error => {
+          console.error(`Error updating patient calendar event ${calendarEventId}:`, error);
+        })
+      );
+    }
+
+    // Update clinic calendar event
+    if (appointment.clinicBranchId) {
+      const clinicEventRef = doc(
+        db,
+        `${CLINICS_COLLECTION}/${appointment.clinicBranchId}/${CALENDAR_COLLECTION}/${calendarEventId}`
+      );
+      updatePromises.push(
+        updateDoc(clinicEventRef, updateData).catch(error => {
+          console.error(`Error updating clinic calendar event ${calendarEventId}:`, error);
+        })
+      );
+    }
+
+    // Wait for all updates to complete
+    await Promise.all(updatePromises);
+    console.log(`Successfully updated calendar event ${calendarEventId} status to ${calendarStatus} across all collections`);
+  } catch (error) {
+    console.error(`Error updating calendar events for appointment ${appointment.id}:`, error);
+    // Don't throw error to avoid failing the appointment update
+  }
+}
+
+/**
+ * Gets an appointment by its ID.
+ *
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @returns The appointment or null if not found
+ */
+export async function getAppointmentByIdUtil(
+  db: Firestore,
+  appointmentId: string,
+): Promise<Appointment | null> {
+  try {
+    const appointmentDoc = await getDoc(doc(db, APPOINTMENTS_COLLECTION, appointmentId));
+
+    if (!appointmentDoc.exists()) {
+      return null;
+    }
+
+    return appointmentDoc.data() as Appointment;
+  } catch (error) {
+    console.error(`Error getting appointment ${appointmentId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Searches for appointments based on various criteria.
+ *
+ * @param db Firestore instance
+ * @param params Search parameters
+ * @returns Found appointments and the last document for pagination
+ */
+export async function searchAppointmentsUtil(
+  db: Firestore,
+  params: SearchAppointmentsParams,
+): Promise<{ appointments: Appointment[]; lastDoc: DocumentSnapshot | null }> {
+  try {
+    const constraints: QueryConstraint[] = [];
+
+    // Add filters based on provided params
+    if (params.patientId) {
+      constraints.push(where('patientId', '==', params.patientId));
+    }
+
+    if (params.practitionerId) {
+      constraints.push(where('practitionerId', '==', params.practitionerId));
+    }
+
+    if (params.clinicBranchId) {
+      constraints.push(where('clinicBranchId', '==', params.clinicBranchId));
+    }
+
+    if (params.startDate) {
+      constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(params.startDate)));
+    }
+
+    if (params.endDate) {
+      constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(params.endDate)));
+    }
+
+    if (params.status) {
+      if (Array.isArray(params.status)) {
+        // If multiple statuses, use in operator
+        constraints.push(where('status', 'in', params.status));
+      } else {
+        // Single status
+        constraints.push(where('status', '==', params.status));
+      }
+    }
+
+    // Add ordering
+    constraints.push(orderBy('appointmentStartTime', 'asc'));
+
+    // Add pagination if specified
+    if (params.limit) {
+      constraints.push(limit(params.limit));
+    }
+
+    if (params.startAfter) {
+      constraints.push(startAfter(params.startAfter));
+    }
+
+    // Execute query
+    const q = query(collection(db, APPOINTMENTS_COLLECTION), ...constraints);
+    const querySnapshot = await getDocs(q);
+
+    // Extract results
+    const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
+
+    // Get last document for pagination
+    const lastDoc =
+      querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
+
+    return { appointments, lastDoc };
+  } catch (error) {
+    console.error('Error searching appointments:', error);
+    throw error;
+  }
+}