@blackcode_sa/metaestetics-api 1.5.16 → 1.5.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.5.16",
+  "version": "1.5.17",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/index.ts

@@ -96,6 +96,8 @@ export type {
   UpdateMedicationData,
   Allergy,
   PatientProfileComplete,
+  SearchPatientsParams,
+  RequesterInfo,
 } from "./types/patient";
 export {
   Gender,

package/src/services/calendar/calendar-refactored.service.ts

@@ -16,6 +16,9 @@ import {
   TimeSlot,
   CreateAppointmentParams,
   UpdateAppointmentParams,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
+  DateRange,
 } from "../../types/calendar";
 import {
   PRACTITIONERS_COLLECTION,
@@ -42,6 +45,9 @@ import {
   getDocs,
   setDoc,
   updateDoc,
+  QueryConstraint,
+  CollectionReference,
+  DocumentData,
 } from "firebase/firestore";
 import {
   createAppointmentSchema,
@@ -54,6 +60,7 @@ import {
   updateAppointmentUtil,
   deleteAppointmentUtil,
 } from "./utils/appointment.utils";
+import { searchCalendarEventsUtil } from "./utils/calendar-event.utils";
 import { SyncedCalendarsService } from "./synced-calendars.service";
 import { Timestamp as FirestoreTimestamp } from "firebase-admin/firestore";
 
@@ -776,6 +783,146 @@ export class CalendarServiceV2 extends BaseService {
     */
   }
 
+  /**
+   * Searches for calendar events based on specified criteria.
+   *
+   * @param {SearchCalendarEventsParams} params - The search parameters.
+   * @param {SearchLocationEnum} params.searchLocation - The primary location to search (practitioner, patient, or clinic).
+   * @param {string} params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for.
+   * @param {string} [params.clinicId] - Optional clinic ID to filter by.
+   * @param {string} [params.practitionerId] - Optional practitioner ID to filter by.
+   * @param {string} [params.patientId] - Optional patient ID to filter by.
+   * @param {string} [params.procedureId] - Optional procedure ID to filter by.
+   * @param {DateRange} [params.dateRange] - Optional date range to filter by (event start time).
+   * @param {CalendarEventStatus} [params.eventStatus] - Optional event status to filter by.
+   * @param {CalendarEventType} [params.eventType] - Optional event type to filter by.
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of matching calendar events.
+   * @throws {Error} If the search location requires an entity ID that is not provided.
+   */
+  async searchCalendarEvents(
+    params: SearchCalendarEventsParams
+  ): Promise<CalendarEvent[]> {
+    // Use the utility function to perform the search
+    return searchCalendarEventsUtil(this.db, params);
+  }
+
+  /**
+   * Gets a doctor's upcoming appointments for a specific date range
+   *
+   * @param {string} doctorId - ID of the practitioner
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to CONFIRMED)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPractitionerUpcomingAppointments(
+    doctorId: string,
+    startDate: Date,
+    endDate: Date,
+    status: CalendarEventStatus = CalendarEventStatus.CONFIRMED
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PRACTITIONER,
+      entityId: doctorId,
+      dateRange,
+      eventStatus: status,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets a patient's appointments for a specific date range
+   *
+   * @param {string} patientId - ID of the patient
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to all non-canceled appointments)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPatientAppointments(
+    patientId: string,
+    startDate: Date,
+    endDate: Date,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PATIENT,
+      entityId: patientId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets all appointments for a clinic within a specific date range
+   *
+   * @param {string} clinicId - ID of the clinic
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {string} [doctorId] - Optional doctor ID to filter by
+   * @param {CalendarEventStatus} [status] - Optional status filter
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getClinicAppointments(
+    clinicId: string,
+    startDate: Date,
+    endDate: Date,
+    doctorId?: string,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.CLINIC,
+      entityId: clinicId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add doctor filter if provided
+    if (doctorId) {
+      searchParams.practitionerId = doctorId;
+    }
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
   // #endregion
 
   // #region Private Helper Methods

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

@@ -24,6 +24,8 @@ import {
   CreateCalendarEventData,
   UpdateCalendarEventData,
   CALENDAR_COLLECTION,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
 } from "../../../types/calendar";
 import { PRACTITIONERS_COLLECTION } from "../../../types/practitioner";
 import { PATIENTS_COLLECTION } from "../../../types/patient";
@@ -508,3 +510,137 @@ export async function deleteClinicCalendarEventUtil(
   );
   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 root CALENDAR_COLLECTION for events associated with the clinic
+      baseCollectionPath = 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
+    constraints.push(where("eventTime.start", ">=", filters.dateRange.start));
+    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);
+
+    const events = querySnapshot.docs.map(
+      (doc) => ({ id: doc.id, ...doc.data() } as CalendarEvent)
+    );
+
+    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 [];
+  }
+}

package/src/services/calendar/utils/index.ts

@@ -1,8 +1,8 @@
-// Export all calendar event utilities
+// Export core calendar utilities
 export * from "./calendar-event.utils";
-
-// Export all synced calendar utilities
 export * from "./synced-calendar.utils";
-
-// Export all Google Calendar utilities
 export * from "./google-calendar.utils";
+export * from "./appointment.utils";
+
+// Note: Other utility files (clinic.utils.ts, patient.utils.ts, practitioner.utils.ts, docs.utils.ts)
+// should be imported directly where needed to avoid naming conflicts

package/src/services/patient/patient.service.ts

@@ -29,6 +29,8 @@ import {
   UpdateMedicationData,
   PatientDoctor,
   PatientClinic,
+  SearchPatientsParams,
+  RequesterInfo,
 } from "../../types/patient";
 import { Auth } from "firebase/auth";
 import { Firestore } from "firebase/firestore";
@@ -48,6 +50,7 @@ import {
   deleteProfilePhotoUtil,
   updatePatientProfileUtil,
   updatePatientProfileByUserRefUtil,
+  searchPatientsUtil,
 } from "./utils/profile.utils";
 
 import {
@@ -468,4 +471,30 @@ export class PatientService extends BaseService {
   ): Promise<PatientProfile> {
     return updatePatientProfileByUserRefUtil(this.db, userRef, data);
   }
+
+  /**
+   * Searches for patient profiles based on clinic/practitioner association.
+   * Requires information about the requester for security checks.
+   *
+   * @param {SearchPatientsParams} params - The search criteria (clinicId, practitionerId).
+   * @param {RequesterInfo} requester - Information about the user performing the search (ID, role, associated IDs).
+   * @returns {Promise<PatientProfile[]>} A promise resolving to an array of matching patient profiles.
+   */
+  async searchPatients(
+    params: SearchPatientsParams,
+    requester: RequesterInfo
+  ): Promise<PatientProfile[]> {
+    // We can potentially add more service-level logic here in the future,
+    // like fetching additional data or enriching the results.
+    // For now, we delegate directly to the utility function.
+    console.log(
+      `[PatientService.searchPatients] Initiating search with params:`,
+      params,
+      `by requester:`,
+      requester
+    );
+
+    // The utility function already handles validation and security checks.
+    return searchPatientsUtil(this.db, params, requester);
+  }
 }

package/src/services/patient/utils/medical-stuff.utils.ts

@@ -2,6 +2,7 @@ import {
   getDoc,
   updateDoc,
   arrayUnion,
+  arrayRemove,
   Firestore,
   serverTimestamp,
   Timestamp,
@@ -27,10 +28,32 @@ export const addDoctorUtil = async (
     isActive: true,
   };
 
-  await updateDoc(getPatientDocRef(db, patientId), {
-    doctors: arrayUnion(newDoctor),
+  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  if (!patientDoc.exists()) throw new Error("Patient profile not found");
+  const patientData = patientDoc.data() as PatientProfile;
+  const existingDoctorIndex = patientData.doctors?.findIndex(
+    (d) => d.userRef === doctorRef
+  );
+
+  const updates: any = {
     updatedAt: serverTimestamp(),
-  });
+    doctorIds: arrayUnion(doctorRef),
+  };
+
+  if (existingDoctorIndex !== undefined && existingDoctorIndex > -1) {
+    const updatedDoctors = [...patientData.doctors];
+    updatedDoctors[existingDoctorIndex] = {
+      ...updatedDoctors[existingDoctorIndex],
+      isActive: true,
+      assignedAt: Timestamp.now(),
+      assignedBy,
+    };
+    updates.doctors = updatedDoctors;
+  } else {
+    updates.doctors = arrayUnion(newDoctor);
+  }
+
+  await updateDoc(getPatientDocRef(db, patientId), updates);
 };
 
 export const removeDoctorUtil = async (
@@ -38,16 +61,19 @@ export const removeDoctorUtil = async (
   patientId: string,
   doctorRef: string
 ): Promise<void> => {
-  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  const patientDocRef = getPatientDocRef(db, patientId);
+  const patientDoc = await getDoc(patientDocRef);
   if (!patientDoc.exists()) throw new Error("Patient profile not found");
 
   const patientData = patientDoc.data() as PatientProfile;
-  const updatedDoctors = patientData.doctors.map((doctor) =>
-    doctor.userRef === doctorRef ? { ...doctor, isActive: false } : doctor
-  );
 
-  await updateDoc(getPatientDocRef(db, patientId), {
-    doctors: updatedDoctors,
+  // Filter out the doctor object by userRef
+  const updatedDoctors =
+    patientData.doctors?.filter((doctor) => doctor.userRef !== doctorRef) || []; // Ensure it's an array even if doctors field didn't exist or was empty
+
+  await updateDoc(patientDocRef, {
+    doctors: updatedDoctors, // Set the filtered array
+    doctorIds: arrayRemove(doctorRef), // Remove ID from the denormalized list
     updatedAt: serverTimestamp(),
   });
 };
@@ -66,10 +92,32 @@ export const addClinicUtil = async (
     isActive: true,
   };
 
-  await updateDoc(getPatientDocRef(db, patientId), {
-    clinics: arrayUnion(newClinic),
+  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  if (!patientDoc.exists()) throw new Error("Patient profile not found");
+  const patientData = patientDoc.data() as PatientProfile;
+  const existingClinicIndex = patientData.clinics?.findIndex(
+    (c) => c.clinicId === clinicId
+  );
+
+  const updates: any = {
     updatedAt: serverTimestamp(),
-  });
+    clinicIds: arrayUnion(clinicId),
+  };
+
+  if (existingClinicIndex !== undefined && existingClinicIndex > -1) {
+    const updatedClinics = [...patientData.clinics];
+    updatedClinics[existingClinicIndex] = {
+      ...updatedClinics[existingClinicIndex],
+      isActive: true,
+      assignedAt: Timestamp.now(),
+      assignedBy,
+    };
+    updates.clinics = updatedClinics;
+  } else {
+    updates.clinics = arrayUnion(newClinic);
+  }
+
+  await updateDoc(getPatientDocRef(db, patientId), updates);
 };
 
 export const removeClinicUtil = async (
@@ -77,16 +125,19 @@ export const removeClinicUtil = async (
   patientId: string,
   clinicId: string
 ): Promise<void> => {
-  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  const patientDocRef = getPatientDocRef(db, patientId);
+  const patientDoc = await getDoc(patientDocRef);
   if (!patientDoc.exists()) throw new Error("Patient profile not found");
 
   const patientData = patientDoc.data() as PatientProfile;
-  const updatedClinics = patientData.clinics.map((clinic) =>
-    clinic.clinicId === clinicId ? { ...clinic, isActive: false } : clinic
-  );
 
-  await updateDoc(getPatientDocRef(db, patientId), {
-    clinics: updatedClinics,
+  // Filter out the clinic object by clinicId
+  const updatedClinics =
+    patientData.clinics?.filter((clinic) => clinic.clinicId !== clinicId) || []; // Ensure it's an array
+
+  await updateDoc(patientDocRef, {
+    clinics: updatedClinics, // Set the filtered array
+    clinicIds: arrayRemove(clinicId), // Remove ID from the denormalized list
     updatedAt: serverTimestamp(),
   });
 };

package/src/services/patient/utils/profile.utils.ts

@@ -8,6 +8,11 @@ import {
   increment,
   Firestore,
   Timestamp,
+  collection,
+  query,
+  where,
+  getDocs,
+  QueryConstraint,
 } from "firebase/firestore";
 import {
   ref,
@@ -21,10 +26,15 @@ import {
   PatientProfile,
   CreatePatientProfileData,
   Gender,
+  SearchPatientsParams,
+  RequesterInfo,
+  PATIENTS_COLLECTION,
 } from "../../../types/patient";
 import {
   patientProfileSchema,
   createPatientProfileSchema,
+  searchPatientsSchema,
+  requesterInfoSchema,
 } from "../../../validations/patient.schema";
 import {
   getPatientDocRef,
@@ -65,6 +75,8 @@ export const createPatientProfileUtil = async (
       isVerified: validatedData.isVerified,
       doctors: validatedData.doctors || [],
       clinics: validatedData.clinics || [],
+      doctorIds: validatedData.doctors?.map((d) => d.userRef) || [],
+      clinicIds: validatedData.clinics?.map((c) => c.clinicId) || [],
       createdAt: serverTimestamp(),
       updatedAt: serverTimestamp(),
     };
@@ -398,3 +410,107 @@ export const testCreateSubDocuments = async (
     throw error;
   }
 };
+
+/**
+ * Searches for patient profiles based on clinic and/or practitioner association.
+ * Applies security checks based on the requester's role and associations.
+ *
+ * @param {Firestore} db - Firestore instance.
+ * @param {SearchPatientsParams} params - Search criteria (clinicId, practitionerId).
+ * @param {RequesterInfo} requester - Information about the user performing the search.
+ * @returns {Promise<PatientProfile[]>} A promise resolving to an array of matching patient profiles.
+ */
+export const searchPatientsUtil = async (
+  db: Firestore,
+  params: SearchPatientsParams,
+  requester: RequesterInfo
+): Promise<PatientProfile[]> => {
+  // Validate input
+  searchPatientsSchema.parse(params);
+  requesterInfoSchema.parse(requester);
+
+  const constraints: QueryConstraint[] = [];
+  const patientsCollectionRef = collection(db, PATIENTS_COLLECTION);
+
+  // --- Security Checks & Initial Filtering ---
+
+  if (requester.role === "clinic_admin") {
+    // Clinic admin can only search within their own clinic
+    if (!requester.associatedClinicId) {
+      throw new Error(
+        "Associated clinic ID is required for clinic admin search."
+      );
+    }
+    // If the search params specify a different clinic, it's an invalid request for this admin.
+    if (params.clinicId && params.clinicId !== requester.associatedClinicId) {
+      console.warn(
+        `Clinic admin (${requester.id}) attempted to search outside their associated clinic (${requester.associatedClinicId})`
+      );
+      return []; // Or throw an error
+    }
+
+    // **Mandatory filter**: Ensure patients belong to the admin's clinic.
+    constraints.push(
+      where("clinicIds", "array-contains", requester.associatedClinicId)
+    );
+
+    // Optional filter: If practitionerId is also provided, filter by that practitioner *within the admin's clinic*.
+    if (params.practitionerId) {
+      constraints.push(
+        where("doctorIds", "array-contains", params.practitionerId)
+      );
+      // We might need an additional check here if the practitioner MUST work at the admin's clinic.
+      // This would require fetching practitioner data or having denormalized clinic IDs on the practitioner.
+    }
+  } else if (requester.role === "practitioner") {
+    // Practitioner can only search for their own patients.
+    if (!requester.associatedPractitionerId) {
+      throw new Error(
+        "Associated practitioner ID is required for practitioner search."
+      );
+    }
+    // If the search params specify a different practitioner, it's invalid.
+    if (
+      params.practitionerId &&
+      params.practitionerId !== requester.associatedPractitionerId
+    ) {
+      console.warn(
+        `Practitioner (${requester.id}) attempted to search for patients of another practitioner (${params.practitionerId})`
+      );
+      return []; // Or throw an error
+    }
+
+    // **Mandatory filter**: Ensure patients are associated with this practitioner.
+    constraints.push(
+      where("doctorIds", "array-contains", requester.associatedPractitionerId)
+    );
+
+    // Optional filter: If clinicId is provided, filter by patients of this practitioner *at that specific clinic*.
+    if (params.clinicId) {
+      constraints.push(where("clinicIds", "array-contains", params.clinicId));
+      // Similar to above, we might need to check if the practitioner actually works at this clinic.
+    }
+  } else {
+    // Should not happen due to validation, but good practice to handle.
+    throw new Error("Invalid requester role.");
+  }
+
+  // --- Execute Query ---
+  try {
+    const finalQuery = query(patientsCollectionRef, ...constraints);
+    const querySnapshot = await getDocs(finalQuery);
+
+    const patients = querySnapshot.docs.map(
+      (doc) => doc.data() as PatientProfile
+    );
+
+    console.log(
+      `[searchPatientsUtil] Found ${patients.length} patients matching criteria.`
+    );
+    return patients;
+  } catch (error) {
+    console.error("[searchPatientsUtil] Error searching patients:", error);
+    // Consider logging more details or re-throwing a specific error type
+    return []; // Return empty array on error
+  }
+};