@blackcode_sa/metaestetics-api 1.12.65 → 1.12.67

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

@@ -1,510 +1,510 @@
-import {
-  getDoc,
-  setDoc,
-  updateDoc,
-  arrayUnion,
-  arrayRemove,
-  serverTimestamp,
-  increment,
-  Firestore,
-  Timestamp,
-  collection,
-  query,
-  where,
-  getDocs,
-  QueryConstraint,
-  limit,
-  startAfter,
-  doc,
-} from "firebase/firestore";
-import { z } from "zod";
-import {
-  PatientProfile,
-  CreatePatientProfileData,
-  Gender,
-  SearchPatientsParams,
-  RequesterInfo,
-  PATIENTS_COLLECTION,
-} from "../../../types/patient";
-import {
-  patientProfileSchema,
-  createPatientProfileSchema,
-  searchPatientsSchema,
-  requesterInfoSchema,
-} from "../../../validations/patient.schema";
-import {
-  getPatientDocRef,
-  getPatientDocRefByUserRef,
-  initSensitiveInfoDocIfNotExists,
-  getSensitiveInfoDocRef,
-  getMedicalInfoDocRef,
-} from "./docs.utils";
-import { ensureMedicalInfoExists } from "./medical.utils";
-import { DEFAULT_MEDICAL_INFO } from "../../../types/patient/medical-info.types";
-
-// Funkcije za rad sa profilom
-export const createPatientProfileUtil = async (
-  db: Firestore,
-  data: CreatePatientProfileData,
-  generateId: () => string
-): Promise<PatientProfile> => {
-  try {
-    console.log("[createPatientProfileUtil] Starting patient profile creation");
-    const validatedData = createPatientProfileSchema.parse(data);
-
-    // This utility is for creating standard profiles, so userRef is required here.
-    if (!validatedData.userRef) {
-      throw new Error(
-        "userRef is required to create a standard patient profile."
-      );
-    }
-
-    const patientId = generateId();
-    console.log(`[createPatientProfileUtil] Generated patientId: ${patientId}`);
-
-    const patientData: Omit<PatientProfile, "createdAt" | "updatedAt"> & {
-      createdAt: ReturnType<typeof serverTimestamp>;
-      updatedAt: ReturnType<typeof serverTimestamp>;
-    } = {
-      id: patientId,
-      userRef: validatedData.userRef,
-      displayName: validatedData.displayName,
-      expoTokens: validatedData.expoTokens,
-      gamification: validatedData.gamification || {
-        level: 1,
-        points: 0,
-      },
-      isActive: validatedData.isActive,
-      isVerified: validatedData.isVerified,
-      isManual: validatedData.isManual,
-      doctors: validatedData.doctors || [],
-      clinics: validatedData.clinics || [],
-      doctorIds: validatedData.doctors?.map((d) => d.userRef) || [],
-      clinicIds: validatedData.clinics?.map((c) => c.clinicId) || [],
-      createdAt: serverTimestamp(),
-      updatedAt: serverTimestamp(),
-    };
-
-    patientProfileSchema.parse({
-      ...patientData,
-      createdAt: Timestamp.now(),
-      updatedAt: Timestamp.now(),
-    });
-
-    await setDoc(getPatientDocRef(db, patientId), patientData);
-
-    // Create blank sensitive info document using the utility function
-    console.log(`[createPatientProfileUtil] Creating sensitive info document`);
-    let sensitiveInfoSuccess = false;
-    try {
-      const sensitiveInfoCreated = await initSensitiveInfoDocIfNotExists(
-        db,
-        patientId,
-        validatedData.userRef
-      );
-      console.log(
-        `[createPatientProfileUtil] Sensitive info document creation result: ${
-          sensitiveInfoCreated
-            ? "Document already existed"
-            : "New document created"
-        }`
-      );
-      sensitiveInfoSuccess = true;
-    } catch (sensitiveError) {
-      console.error(
-        `[createPatientProfileUtil] Error creating sensitive info:`,
-        sensitiveError
-      );
-      // Don't throw the error, we'll try the direct method
-    }
-
-    // Create blank medical info document using the utility function
-    console.log(`[createPatientProfileUtil] Creating medical info document`);
-    let medicalInfoSuccess = false;
-    try {
-      await ensureMedicalInfoExists(db, patientId, validatedData.userRef);
-      console.log(
-        `[createPatientProfileUtil] Medical info document created successfully`
-      );
-      medicalInfoSuccess = true;
-    } catch (medicalError) {
-      console.error(
-        `[createPatientProfileUtil] Error creating medical info:`,
-        medicalError
-      );
-      // Don't throw the error, we'll try the direct method
-    }
-
-    // If either utility function failed, try the direct method
-    if (!sensitiveInfoSuccess || !medicalInfoSuccess) {
-      console.log(
-        `[createPatientProfileUtil] Using fallback method to create documents`
-      );
-      try {
-        await testCreateSubDocuments(db, patientId, validatedData.userRef);
-        console.log(
-          `[createPatientProfileUtil] Fallback method completed successfully`
-        );
-      } catch (fallbackError) {
-        console.error(
-          `[createPatientProfileUtil] Fallback method failed:`,
-          fallbackError
-        );
-        // Still continue to return the patient profile
-      }
-    }
-
-    console.log(`[createPatientProfileUtil] Verifying patient document exists`);
-    const patientDoc = await getDoc(getPatientDocRef(db, patientId));
-    if (!patientDoc.exists()) {
-      console.error(
-        `[createPatientProfileUtil] Patient document not found after creation`
-      );
-      throw new Error("Failed to create patient profile");
-    }
-
-    console.log(
-      `[createPatientProfileUtil] Patient profile creation completed successfully`
-    );
-    return patientDoc.data() as PatientProfile;
-  } catch (error) {
-    console.error(
-      `[createPatientProfileUtil] Error in patient profile creation:`,
-      error
-    );
-    if (error instanceof z.ZodError) {
-      throw new Error("Invalid patient data: " + error.message);
-    }
-    throw error;
-  }
-};
-
-export const getPatientProfileUtil = async (
-  db: Firestore,
-  patientId: string
-): Promise<PatientProfile | null> => {
-  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
-  return patientDoc.exists() ? (patientDoc.data() as PatientProfile) : null;
-};
-
-export const getPatientProfileByUserRefUtil = async (
-  db: Firestore,
-  userRef: string
-): Promise<PatientProfile | null> => {
-  try {
-    const docRef = await getPatientDocRefByUserRef(db, userRef);
-    const patientDoc = await getDoc(docRef);
-    return patientDoc.exists() ? (patientDoc.data() as PatientProfile) : null;
-  } catch (error) {
-    return null;
-  }
-};
-
-// Pomoćne funkcije za tokene i poene
-export const addExpoTokenUtil = async (
-  db: Firestore,
-  patientId: string,
-  token: string
-): Promise<void> => {
-  await updateDoc(getPatientDocRef(db, patientId), {
-    expoTokens: arrayUnion(token),
-    updatedAt: serverTimestamp(),
-  });
-};
-
-export const removeExpoTokenUtil = async (
-  db: Firestore,
-  patientId: string,
-  token: string
-): Promise<void> => {
-  await updateDoc(getPatientDocRef(db, patientId), {
-    expoTokens: arrayRemove(token),
-    updatedAt: serverTimestamp(),
-  });
-};
-
-export const addPointsUtil = async (
-  db: Firestore,
-  patientId: string,
-  points: number
-): Promise<void> => {
-  await updateDoc(getPatientDocRef(db, patientId), {
-    "gamification.points": increment(points),
-    updatedAt: serverTimestamp(),
-  });
-};
-
-export const updatePatientProfileUtil = async (
-  db: Firestore,
-  patientId: string,
-  data: Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">>
-): Promise<PatientProfile> => {
-  try {
-    const updateData = {
-      ...data,
-      updatedAt: serverTimestamp(),
-    };
-
-    await updateDoc(getPatientDocRef(db, patientId), updateData);
-
-    const updatedDoc = await getDoc(getPatientDocRef(db, patientId));
-    if (!updatedDoc.exists()) {
-      throw new Error("Patient profile not found after update");
-    }
-
-    return updatedDoc.data() as PatientProfile;
-  } catch (error: unknown) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to update patient profile: ${errorMessage}`);
-  }
-};
-
-export const updatePatientProfileByUserRefUtil = async (
-  db: Firestore,
-  userRef: string,
-  data: Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">>
-): Promise<PatientProfile> => {
-  try {
-    const docRef = await getPatientDocRefByUserRef(db, userRef);
-    const patientDoc = await getDoc(docRef);
-
-    if (!patientDoc.exists()) {
-      throw new Error("Patient profile not found");
-    }
-
-    const patientData = patientDoc.data() as PatientProfile;
-    return updatePatientProfileUtil(db, patientData.id, data);
-  } catch (error: unknown) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Failed to update patient profile by user ref: ${errorMessage}`
-    );
-  }
-};
-
-/**
- * Test function to directly create sensitive and medical info documents
- * This is for debugging purposes only
- */
-export const testCreateSubDocuments = async (
-  db: Firestore,
-  patientId: string,
-  userRef: string
-): Promise<void> => {
-  console.log(
-    `[testCreateSubDocuments] Starting test for patientId: ${patientId}, userRef: ${userRef}`
-  );
-
-  try {
-    // Test sensitive info creation
-    console.log(`[testCreateSubDocuments] Testing sensitive info creation`);
-    const sensitiveInfoRef = getSensitiveInfoDocRef(db, patientId);
-    console.log(
-      `[testCreateSubDocuments] Sensitive info path: ${sensitiveInfoRef.path}`
-    );
-
-    const defaultSensitiveInfo = {
-      patientId,
-      userRef,
-      photoUrl: "",
-      firstName: "Name",
-      lastName: "Surname",
-      dateOfBirth: Timestamp.now(),
-      gender: Gender.PREFER_NOT_TO_SAY,
-      email: "test@example.com",
-      phoneNumber: "",
-      createdAt: Timestamp.now(),
-      updatedAt: Timestamp.now(),
-    };
-
-    await setDoc(sensitiveInfoRef, defaultSensitiveInfo);
-    console.log(
-      `[testCreateSubDocuments] Sensitive info document created directly`
-    );
-
-    // Test medical info creation
-    console.log(`[testCreateSubDocuments] Testing medical info creation`);
-    const medicalInfoRef = getMedicalInfoDocRef(db, patientId);
-    console.log(
-      `[testCreateSubDocuments] Medical info path: ${medicalInfoRef.path}`
-    );
-
-    const defaultMedicalInfo = {
-      ...DEFAULT_MEDICAL_INFO,
-      patientId,
-      lastUpdated: Timestamp.now(),
-      updatedBy: userRef,
-    };
-
-    await setDoc(medicalInfoRef, defaultMedicalInfo);
-    console.log(
-      `[testCreateSubDocuments] Medical info document created directly`
-    );
-
-    console.log(`[testCreateSubDocuments] Test completed successfully`);
-  } catch (error) {
-    console.error(`[testCreateSubDocuments] Error:`, error);
-    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
-  }
-};
-
-/**
- * Retrieves all patient profiles from the database.
- *
- * @param {Firestore} db - Firestore instance
- * @param {Object} options - Optional parameters for pagination
- * @param {number} options.limit - Maximum number of profiles to return
- * @param {string} options.startAfter - The ID of the document to start after (for pagination)
- * @returns {Promise<PatientProfile[]>} A promise resolving to an array of all patient profiles
- */
-export const getAllPatientsUtil = async (
-  db: Firestore,
-  options?: { limit?: number; startAfter?: string }
-): Promise<PatientProfile[]> => {
-  try {
-    console.log(
-      `[getAllPatientsUtil] Fetching patients with options:`,
-      options
-    );
-
-    const patientsCollection = collection(db, PATIENTS_COLLECTION);
-
-    let q = query(patientsCollection);
-
-    // Apply pagination if needed
-    if (options?.limit) {
-      q = query(q, limit(options.limit));
-    }
-
-    // If startAfter is provided, get that document and use it for pagination
-    if (options?.startAfter) {
-      const startAfterDoc = await getDoc(
-        doc(db, PATIENTS_COLLECTION, options.startAfter)
-      );
-      if (startAfterDoc.exists()) {
-        q = query(q, startAfter(startAfterDoc));
-      }
-    }
-
-    const patientsSnapshot = await getDocs(q);
-
-    const patients: PatientProfile[] = [];
-    patientsSnapshot.forEach((doc) => {
-      patients.push(doc.data() as PatientProfile);
-    });
-
-    console.log(`[getAllPatientsUtil] Found ${patients.length} patients`);
-    return patients;
-  } catch (error) {
-    console.error(`[getAllPatientsUtil] Error fetching patients:`, error);
-    throw new Error(
-      `Failed to retrieve patients: ${
-        error instanceof Error ? error.message : String(error)
-      }`
-    );
-  }
-};
+import {
+  getDoc,
+  setDoc,
+  updateDoc,
+  arrayUnion,
+  arrayRemove,
+  serverTimestamp,
+  increment,
+  Firestore,
+  Timestamp,
+  collection,
+  query,
+  where,
+  getDocs,
+  QueryConstraint,
+  limit,
+  startAfter,
+  doc,
+} from "firebase/firestore";
+import { z } from "zod";
+import {
+  PatientProfile,
+  CreatePatientProfileData,
+  Gender,
+  SearchPatientsParams,
+  RequesterInfo,
+  PATIENTS_COLLECTION,
+} from "../../../types/patient";
+import {
+  patientProfileSchema,
+  createPatientProfileSchema,
+  searchPatientsSchema,
+  requesterInfoSchema,
+} from "../../../validations/patient.schema";
+import {
+  getPatientDocRef,
+  getPatientDocRefByUserRef,
+  initSensitiveInfoDocIfNotExists,
+  getSensitiveInfoDocRef,
+  getMedicalInfoDocRef,
+} from "./docs.utils";
+import { ensureMedicalInfoExists } from "./medical.utils";
+import { DEFAULT_MEDICAL_INFO } from "../../../types/patient/medical-info.types";
+
+// Funkcije za rad sa profilom
+export const createPatientProfileUtil = async (
+  db: Firestore,
+  data: CreatePatientProfileData,
+  generateId: () => string
+): Promise<PatientProfile> => {
+  try {
+    console.log("[createPatientProfileUtil] Starting patient profile creation");
+    const validatedData = createPatientProfileSchema.parse(data);
+
+    // This utility is for creating standard profiles, so userRef is required here.
+    if (!validatedData.userRef) {
+      throw new Error(
+        "userRef is required to create a standard patient profile."
+      );
+    }
+
+    const patientId = generateId();
+    console.log(`[createPatientProfileUtil] Generated patientId: ${patientId}`);
+
+    const patientData: Omit<PatientProfile, "createdAt" | "updatedAt"> & {
+      createdAt: ReturnType<typeof serverTimestamp>;
+      updatedAt: ReturnType<typeof serverTimestamp>;
+    } = {
+      id: patientId,
+      userRef: validatedData.userRef,
+      displayName: validatedData.displayName,
+      expoTokens: validatedData.expoTokens,
+      gamification: validatedData.gamification || {
+        level: 1,
+        points: 0,
+      },
+      isActive: validatedData.isActive,
+      isVerified: validatedData.isVerified,
+      isManual: validatedData.isManual,
+      doctors: validatedData.doctors || [],
+      clinics: validatedData.clinics || [],
+      doctorIds: validatedData.doctors?.map((d) => d.userRef) || [],
+      clinicIds: validatedData.clinics?.map((c) => c.clinicId) || [],
+      createdAt: serverTimestamp(),
+      updatedAt: serverTimestamp(),
+    };
+
+    patientProfileSchema.parse({
+      ...patientData,
+      createdAt: Timestamp.now(),
+      updatedAt: Timestamp.now(),
+    });
+
+    await setDoc(getPatientDocRef(db, patientId), patientData);
+
+    // Create blank sensitive info document using the utility function
+    console.log(`[createPatientProfileUtil] Creating sensitive info document`);
+    let sensitiveInfoSuccess = false;
+    try {
+      const sensitiveInfoCreated = await initSensitiveInfoDocIfNotExists(
+        db,
+        patientId,
+        validatedData.userRef
+      );
+      console.log(
+        `[createPatientProfileUtil] Sensitive info document creation result: ${
+          sensitiveInfoCreated
+            ? "Document already existed"
+            : "New document created"
+        }`
+      );
+      sensitiveInfoSuccess = true;
+    } catch (sensitiveError) {
+      console.error(
+        `[createPatientProfileUtil] Error creating sensitive info:`,
+        sensitiveError
+      );
+      // Don't throw the error, we'll try the direct method
+    }
+
+    // Create blank medical info document using the utility function
+    console.log(`[createPatientProfileUtil] Creating medical info document`);
+    let medicalInfoSuccess = false;
+    try {
+      await ensureMedicalInfoExists(db, patientId, validatedData.userRef);
+      console.log(
+        `[createPatientProfileUtil] Medical info document created successfully`
+      );
+      medicalInfoSuccess = true;
+    } catch (medicalError) {
+      console.error(
+        `[createPatientProfileUtil] Error creating medical info:`,
+        medicalError
+      );
+      // Don't throw the error, we'll try the direct method
+    }
+
+    // If either utility function failed, try the direct method
+    if (!sensitiveInfoSuccess || !medicalInfoSuccess) {
+      console.log(
+        `[createPatientProfileUtil] Using fallback method to create documents`
+      );
+      try {
+        await testCreateSubDocuments(db, patientId, validatedData.userRef);
+        console.log(
+          `[createPatientProfileUtil] Fallback method completed successfully`
+        );
+      } catch (fallbackError) {
+        console.error(
+          `[createPatientProfileUtil] Fallback method failed:`,
+          fallbackError
+        );
+        // Still continue to return the patient profile
+      }
+    }
+
+    console.log(`[createPatientProfileUtil] Verifying patient document exists`);
+    const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+    if (!patientDoc.exists()) {
+      console.error(
+        `[createPatientProfileUtil] Patient document not found after creation`
+      );
+      throw new Error("Failed to create patient profile");
+    }
+
+    console.log(
+      `[createPatientProfileUtil] Patient profile creation completed successfully`
+    );
+    return patientDoc.data() as PatientProfile;
+  } catch (error) {
+    console.error(
+      `[createPatientProfileUtil] Error in patient profile creation:`,
+      error
+    );
+    if (error instanceof z.ZodError) {
+      throw new Error("Invalid patient data: " + error.message);
+    }
+    throw error;
+  }
+};
+
+export const getPatientProfileUtil = async (
+  db: Firestore,
+  patientId: string
+): Promise<PatientProfile | null> => {
+  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  return patientDoc.exists() ? (patientDoc.data() as PatientProfile) : null;
+};
+
+export const getPatientProfileByUserRefUtil = async (
+  db: Firestore,
+  userRef: string
+): Promise<PatientProfile | null> => {
+  try {
+    const docRef = await getPatientDocRefByUserRef(db, userRef);
+    const patientDoc = await getDoc(docRef);
+    return patientDoc.exists() ? (patientDoc.data() as PatientProfile) : null;
+  } catch (error) {
+    return null;
+  }
+};
+
+// Pomoćne funkcije za tokene i poene
+export const addExpoTokenUtil = async (
+  db: Firestore,
+  patientId: string,
+  token: string
+): Promise<void> => {
+  await updateDoc(getPatientDocRef(db, patientId), {
+    expoTokens: arrayUnion(token),
+    updatedAt: serverTimestamp(),
+  });
+};
+
+export const removeExpoTokenUtil = async (
+  db: Firestore,
+  patientId: string,
+  token: string
+): Promise<void> => {
+  await updateDoc(getPatientDocRef(db, patientId), {
+    expoTokens: arrayRemove(token),
+    updatedAt: serverTimestamp(),
+  });
+};
+
+export const addPointsUtil = async (
+  db: Firestore,
+  patientId: string,
+  points: number
+): Promise<void> => {
+  await updateDoc(getPatientDocRef(db, patientId), {
+    "gamification.points": increment(points),
+    updatedAt: serverTimestamp(),
+  });
+};
+
+export const updatePatientProfileUtil = async (
+  db: Firestore,
+  patientId: string,
+  data: Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">>
+): Promise<PatientProfile> => {
+  try {
+    const updateData = {
+      ...data,
+      updatedAt: serverTimestamp(),
+    };
+
+    await updateDoc(getPatientDocRef(db, patientId), updateData);
+
+    const updatedDoc = await getDoc(getPatientDocRef(db, patientId));
+    if (!updatedDoc.exists()) {
+      throw new Error("Patient profile not found after update");
+    }
+
+    return updatedDoc.data() as PatientProfile;
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to update patient profile: ${errorMessage}`);
+  }
+};
+
+export const updatePatientProfileByUserRefUtil = async (
+  db: Firestore,
+  userRef: string,
+  data: Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">>
+): Promise<PatientProfile> => {
+  try {
+    const docRef = await getPatientDocRefByUserRef(db, userRef);
+    const patientDoc = await getDoc(docRef);
+
+    if (!patientDoc.exists()) {
+      throw new Error("Patient profile not found");
+    }
+
+    const patientData = patientDoc.data() as PatientProfile;
+    return updatePatientProfileUtil(db, patientData.id, data);
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to update patient profile by user ref: ${errorMessage}`
+    );
+  }
+};
+
+/**
+ * Test function to directly create sensitive and medical info documents
+ * This is for debugging purposes only
+ */
+export const testCreateSubDocuments = async (
+  db: Firestore,
+  patientId: string,
+  userRef: string
+): Promise<void> => {
+  console.log(
+    `[testCreateSubDocuments] Starting test for patientId: ${patientId}, userRef: ${userRef}`
+  );
+
+  try {
+    // Test sensitive info creation
+    console.log(`[testCreateSubDocuments] Testing sensitive info creation`);
+    const sensitiveInfoRef = getSensitiveInfoDocRef(db, patientId);
+    console.log(
+      `[testCreateSubDocuments] Sensitive info path: ${sensitiveInfoRef.path}`
+    );
+
+    const defaultSensitiveInfo = {
+      patientId,
+      userRef,
+      photoUrl: "",
+      firstName: "Name",
+      lastName: "Surname",
+      dateOfBirth: Timestamp.now(),
+      gender: Gender.PREFER_NOT_TO_SAY,
+      email: "test@example.com",
+      phoneNumber: "",
+      createdAt: Timestamp.now(),
+      updatedAt: Timestamp.now(),
+    };
+
+    await setDoc(sensitiveInfoRef, defaultSensitiveInfo);
+    console.log(
+      `[testCreateSubDocuments] Sensitive info document created directly`
+    );
+
+    // Test medical info creation
+    console.log(`[testCreateSubDocuments] Testing medical info creation`);
+    const medicalInfoRef = getMedicalInfoDocRef(db, patientId);
+    console.log(
+      `[testCreateSubDocuments] Medical info path: ${medicalInfoRef.path}`
+    );
+
+    const defaultMedicalInfo = {
+      ...DEFAULT_MEDICAL_INFO,
+      patientId,
+      lastUpdated: Timestamp.now(),
+      updatedBy: userRef,
+    };
+
+    await setDoc(medicalInfoRef, defaultMedicalInfo);
+    console.log(
+      `[testCreateSubDocuments] Medical info document created directly`
+    );
+
+    console.log(`[testCreateSubDocuments] Test completed successfully`);
+  } catch (error) {
+    console.error(`[testCreateSubDocuments] Error:`, error);
+    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
+  }
+};
+
+/**
+ * Retrieves all patient profiles from the database.
+ *
+ * @param {Firestore} db - Firestore instance
+ * @param {Object} options - Optional parameters for pagination
+ * @param {number} options.limit - Maximum number of profiles to return
+ * @param {string} options.startAfter - The ID of the document to start after (for pagination)
+ * @returns {Promise<PatientProfile[]>} A promise resolving to an array of all patient profiles
+ */
+export const getAllPatientsUtil = async (
+  db: Firestore,
+  options?: { limit?: number; startAfter?: string }
+): Promise<PatientProfile[]> => {
+  try {
+    console.log(
+      `[getAllPatientsUtil] Fetching patients with options:`,
+      options
+    );
+
+    const patientsCollection = collection(db, PATIENTS_COLLECTION);
+
+    let q = query(patientsCollection);
+
+    // Apply pagination if needed
+    if (options?.limit) {
+      q = query(q, limit(options.limit));
+    }
+
+    // If startAfter is provided, get that document and use it for pagination
+    if (options?.startAfter) {
+      const startAfterDoc = await getDoc(
+        doc(db, PATIENTS_COLLECTION, options.startAfter)
+      );
+      if (startAfterDoc.exists()) {
+        q = query(q, startAfter(startAfterDoc));
+      }
+    }
+
+    const patientsSnapshot = await getDocs(q);
+
+    const patients: PatientProfile[] = [];
+    patientsSnapshot.forEach((doc) => {
+      patients.push(doc.data() as PatientProfile);
+    });
+
+    console.log(`[getAllPatientsUtil] Found ${patients.length} patients`);
+    return patients;
+  } catch (error) {
+    console.error(`[getAllPatientsUtil] Error fetching patients:`, error);
+    throw new Error(
+      `Failed to retrieve patients: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+};