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

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

@@ -1,309 +1,309 @@
-import {
-  collection,
-  getDocs,
-  query,
-  where,
-  doc,
-  updateDoc,
-  Timestamp,
-  DocumentReference,
-  serverTimestamp,
-  orderBy,
-  limit,
-  startAfter,
-  getDoc,
-  FieldPath,
-  WhereFilterOp,
-  Firestore,
-  DocumentSnapshot,
-} from "firebase/firestore";
-import { FirebaseApp } from "firebase/app";
-import { Auth } from "firebase/auth";
-import { BaseService } from "../base.service";
-import {
-  PatientRequirementInstance,
-  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
-  PatientInstructionStatus,
-  PatientRequirementOverallStatus,
-  PatientRequirementInstruction,
-} from "../../types/patient/patient-requirements";
-import { UserRole } from "../../types"; // Assuming UserRole is in the root types
-
-/**
- * Interface for filtering active patient requirements.
- */
-export interface PatientRequirementsFilters {
-  appointmentId?: string | "all"; // Specific appointment, or 'all' for any appointment
-  statuses?: PatientRequirementOverallStatus[];
-  instructionStatuses?: PatientInstructionStatus[]; // Filter by status of individual instructions
-  dueBefore?: Timestamp; // Filter for instructions due before this time
-  dueAfter?: Timestamp; // Filter for instructions due after this time
-}
-
-export class PatientRequirementsService extends BaseService {
-  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
-    super(db, auth, app);
-  }
-
-  private getPatientRequirementsCollectionRef(patientId: string) {
-    return collection(
-      this.db,
-      `patients/${patientId}/${PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME}`
-    );
-  }
-
-  private getPatientRequirementDocRef(
-    patientId: string,
-    instanceId: string
-  ): DocumentReference<PatientRequirementInstance> {
-    return doc(
-      this.getPatientRequirementsCollectionRef(patientId),
-      instanceId
-    ) as DocumentReference<PatientRequirementInstance>;
-  }
-
-  /**
-   * Gets a specific patient requirement instance by its ID.
-   * @param patientId - The ID of the patient.
-   * @param instanceId - The ID of the requirement instance.
-   * @returns The patient requirement instance or null if not found.
-   */
-  async getPatientRequirementInstance(
-    patientId: string,
-    instanceId: string
-  ): Promise<PatientRequirementInstance | null> {
-    const docRef = this.getPatientRequirementDocRef(patientId, instanceId);
-    const docSnap = await getDoc(docRef);
-    if (!docSnap.exists()) {
-      return null;
-    }
-    // Explicitly type data to exclude 'id' before spreading
-    const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
-    return { id: docSnap.id, ...data } as PatientRequirementInstance;
-  }
-
-  /**
-   * Retrieves patient requirement instances based on specified filters.
-   * This is a flexible query method.
-   *
-   * @param patientId - The ID of the patient.
-   * @param filters - Optional filters for appointmentId, overall statuses, instruction statuses, and due timeframes.
-   * @param pageLimit - Optional limit for pagination.
-   * @param lastVisible - Optional last document snapshot for pagination.
-   * @returns A promise resolving to an array of matching patient requirement instances and the last document snapshot.
-   */
-  async getAllPatientRequirementInstances(
-    patientId: string,
-    filters?: PatientRequirementsFilters,
-    pageLimit: number = 20,
-    lastVisible?: DocumentSnapshot
-  ): Promise<{
-    requirements: PatientRequirementInstance[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    const collRef = this.getPatientRequirementsCollectionRef(patientId);
-    let q = query(collRef, orderBy("createdAt", "desc")); // Default sort
-
-    const queryConstraints = [];
-
-    if (filters?.appointmentId && filters.appointmentId !== "all") {
-      queryConstraints.push(
-        where("appointmentId", "==", filters.appointmentId)
-      );
-    }
-
-    if (filters?.statuses && filters.statuses.length > 0) {
-      queryConstraints.push(where("overallStatus", "in", filters.statuses));
-    }
-
-    // Filtering by instruction statuses or due times requires iterating post-fetch
-    // or more complex data modeling if direct querying is essential at scale.
-    // For a "light" service, post-fetch filtering for these is acceptable for now.
-
-    if (lastVisible) {
-      queryConstraints.push(startAfter(lastVisible));
-    }
-    queryConstraints.push(limit(pageLimit));
-
-    q = query(collRef, ...queryConstraints);
-
-    const snapshot = await getDocs(q);
-    let requirements = snapshot.docs.map((docSnap: DocumentSnapshot) => {
-      // Explicitly cast data after ensuring it's not undefined (though .data() on QueryDocumentSnapshot is not undefined)
-      const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
-      return { id: docSnap.id, ...data } as PatientRequirementInstance;
-    });
-
-    // Post-fetch filtering for instruction statuses and due times
-    if (
-      filters?.instructionStatuses &&
-      filters.instructionStatuses.length > 0
-    ) {
-      requirements = requirements.filter((req) =>
-        req.instructions.some((instr) =>
-          filters.instructionStatuses!.includes(instr.status)
-        )
-      );
-    }
-
-    if (filters?.dueBefore) {
-      const dueBeforeMillis = filters.dueBefore.toMillis();
-      requirements = requirements.filter((req) =>
-        req.instructions.some(
-          (instr) => instr.dueTime.toMillis() < dueBeforeMillis
-        )
-      );
-    }
-
-    if (filters?.dueAfter) {
-      const dueAfterMillis = filters.dueAfter.toMillis();
-      requirements = requirements.filter((req) =>
-        req.instructions.some(
-          (instr) => instr.dueTime.toMillis() > dueAfterMillis
-        )
-      );
-    }
-
-    const newLastVisible = snapshot.docs[snapshot.docs.length - 1] || null;
-
-    return { requirements, lastDoc: newLastVisible };
-  }
-
-  /**
-   * Marks a specific instruction within a PatientRequirementInstance as ACTION_TAKEN.
-   * If all instructions are actioned, updates the overallStatus of the instance.
-   *
-   * @param patientId - The ID of the patient.
-   * @param instanceId - The ID of the PatientRequirementInstance.
-   * @param instructionId - The ID of the instruction to complete.
-   * @returns The updated PatientRequirementInstance.
-   * @throws Error if the instance or instruction is not found, or if the instruction is not in a completable state.
-   */
-  async completeInstruction(
-    patientId: string,
-    instanceId: string,
-    instructionId: string
-  ): Promise<PatientRequirementInstance> {
-    const instanceRef = this.getPatientRequirementDocRef(patientId, instanceId);
-    const instanceSnap = await getDoc(instanceRef); // Simplified: getDoc without explicit generic here
-
-    if (!instanceSnap.exists()) {
-      throw new Error(
-        `PatientRequirementInstance ${instanceId} not found for patient ${patientId}.`
-      );
-    }
-
-    // Explicitly cast data after exists check
-    const instanceData = instanceSnap.data() as Omit<
-      PatientRequirementInstance,
-      "id"
-    >;
-    const instance = { id: instanceSnap.id, ...instanceData };
-
-    const instructionIndex = instance.instructions.findIndex(
-      (instr) => instr.instructionId === instructionId
-    );
-
-    if (instructionIndex === -1) {
-      throw new Error(
-        `Instruction ${instructionId} not found in instance ${instanceId}.`
-      );
-    }
-
-    const instructionToUpdate = instance.instructions[instructionIndex];
-
-    // Date enforcement: reject premature completions outside actionable window
-    const currentTime = Timestamp.now();
-    const dueTime = instructionToUpdate.dueTime;
-    if (dueTime) {
-      const dueTimeMs =
-        typeof dueTime === "number"
-          ? dueTime
-          : typeof (dueTime as any).toMillis === "function"
-            ? (dueTime as any).toMillis()
-            : 0;
-      if (dueTimeMs > 0) {
-        const actionableWindowHours =
-          (instructionToUpdate as any).actionableWindow || 24;
-        const windowStartMs =
-          dueTimeMs - actionableWindowHours * 60 * 60 * 1000;
-        if (currentTime.toMillis() < windowStartMs) {
-          throw new Error(
-            `Instruction ${instructionId} cannot be completed yet. ` +
-              `Actionable window starts at ${new Date(windowStartMs).toISOString()}.`
-          );
-        }
-      }
-    }
-
-    // Allow completion if it's PENDING_NOTIFICATION, ACTION_DUE, or even MISSED (if policy allows late completion)
-    if (
-      instructionToUpdate.status !==
-        PatientInstructionStatus.PENDING_NOTIFICATION &&
-      instructionToUpdate.status !== PatientInstructionStatus.ACTION_DUE &&
-      instructionToUpdate.status !== PatientInstructionStatus.MISSED
-    ) {
-      // If already ACTION_TAKEN or CANCELLED, do nothing or throw specific error
-      if (
-        instructionToUpdate.status === PatientInstructionStatus.ACTION_TAKEN
-      ) {
-        console.warn(
-          `Instruction ${instructionId} is already marked as ACTION_TAKEN.`
-        );
-        return instance as PatientRequirementInstance; // Ensure return type matches
-      }
-      throw new Error(
-        `Instruction ${instructionId} is in status ${instructionToUpdate.status} and cannot be marked as completed.`
-      );
-    }
-
-    const now = Timestamp.now();
-    const updatedInstructions = [...instance.instructions];
-    updatedInstructions[instructionIndex] = {
-      ...instructionToUpdate,
-      status: PatientInstructionStatus.ACTION_TAKEN,
-      actionTakenAt: now,
-      updatedAt: now,
-    };
-
-    // Check if all instructions are now ACTION_TAKEN
-    const allActionTaken = updatedInstructions.every(
-      (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
-    );
-
-    let newOverallStatus = instance.overallStatus;
-    if (allActionTaken) {
-      newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
-    } else if (
-      updatedInstructions.some(
-        (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
-      )
-    ) {
-      // If some are taken, but not all, and it was previously just ACTIVE
-      newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
-    }
-
-    const updatePayload: { [key: string]: any } = {
-      // Using a general type for updateDoc payload
-      instructions: updatedInstructions,
-      updatedAt: now,
-    };
-
-    if (newOverallStatus !== instance.overallStatus) {
-      updatePayload.overallStatus = newOverallStatus;
-    }
-
-    await updateDoc(instanceRef, updatePayload);
-
-    // Construct the returned object accurately
-    return {
-      ...instance,
-      instructions: updatedInstructions,
-      updatedAt: now,
-      overallStatus: newOverallStatus,
-    } as PatientRequirementInstance;
-  }
-
-  // Note: As per the request, full CRUD (create, direct update of instance, delete) is not part of this light service,
-  // as those will be handled by Cloud Functions reacting to appointment lifecycle events.
-}
+import {
+  collection,
+  getDocs,
+  query,
+  where,
+  doc,
+  updateDoc,
+  Timestamp,
+  DocumentReference,
+  serverTimestamp,
+  orderBy,
+  limit,
+  startAfter,
+  getDoc,
+  FieldPath,
+  WhereFilterOp,
+  Firestore,
+  DocumentSnapshot,
+} from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { Auth } from "firebase/auth";
+import { BaseService } from "../base.service";
+import {
+  PatientRequirementInstance,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PatientRequirementInstruction,
+} from "../../types/patient/patient-requirements";
+import { UserRole } from "../../types"; // Assuming UserRole is in the root types
+
+/**
+ * Interface for filtering active patient requirements.
+ */
+export interface PatientRequirementsFilters {
+  appointmentId?: string | "all"; // Specific appointment, or 'all' for any appointment
+  statuses?: PatientRequirementOverallStatus[];
+  instructionStatuses?: PatientInstructionStatus[]; // Filter by status of individual instructions
+  dueBefore?: Timestamp; // Filter for instructions due before this time
+  dueAfter?: Timestamp; // Filter for instructions due after this time
+}
+
+export class PatientRequirementsService extends BaseService {
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+  }
+
+  private getPatientRequirementsCollectionRef(patientId: string) {
+    return collection(
+      this.db,
+      `patients/${patientId}/${PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME}`
+    );
+  }
+
+  private getPatientRequirementDocRef(
+    patientId: string,
+    instanceId: string
+  ): DocumentReference<PatientRequirementInstance> {
+    return doc(
+      this.getPatientRequirementsCollectionRef(patientId),
+      instanceId
+    ) as DocumentReference<PatientRequirementInstance>;
+  }
+
+  /**
+   * Gets a specific patient requirement instance by its ID.
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the requirement instance.
+   * @returns The patient requirement instance or null if not found.
+   */
+  async getPatientRequirementInstance(
+    patientId: string,
+    instanceId: string
+  ): Promise<PatientRequirementInstance | null> {
+    const docRef = this.getPatientRequirementDocRef(patientId, instanceId);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) {
+      return null;
+    }
+    // Explicitly type data to exclude 'id' before spreading
+    const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
+    return { id: docSnap.id, ...data } as PatientRequirementInstance;
+  }
+
+  /**
+   * Retrieves patient requirement instances based on specified filters.
+   * This is a flexible query method.
+   *
+   * @param patientId - The ID of the patient.
+   * @param filters - Optional filters for appointmentId, overall statuses, instruction statuses, and due timeframes.
+   * @param pageLimit - Optional limit for pagination.
+   * @param lastVisible - Optional last document snapshot for pagination.
+   * @returns A promise resolving to an array of matching patient requirement instances and the last document snapshot.
+   */
+  async getAllPatientRequirementInstances(
+    patientId: string,
+    filters?: PatientRequirementsFilters,
+    pageLimit: number = 20,
+    lastVisible?: DocumentSnapshot
+  ): Promise<{
+    requirements: PatientRequirementInstance[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    const collRef = this.getPatientRequirementsCollectionRef(patientId);
+    let q = query(collRef, orderBy("createdAt", "desc")); // Default sort
+
+    const queryConstraints = [];
+
+    if (filters?.appointmentId && filters.appointmentId !== "all") {
+      queryConstraints.push(
+        where("appointmentId", "==", filters.appointmentId)
+      );
+    }
+
+    if (filters?.statuses && filters.statuses.length > 0) {
+      queryConstraints.push(where("overallStatus", "in", filters.statuses));
+    }
+
+    // Filtering by instruction statuses or due times requires iterating post-fetch
+    // or more complex data modeling if direct querying is essential at scale.
+    // For a "light" service, post-fetch filtering for these is acceptable for now.
+
+    if (lastVisible) {
+      queryConstraints.push(startAfter(lastVisible));
+    }
+    queryConstraints.push(limit(pageLimit));
+
+    q = query(collRef, ...queryConstraints);
+
+    const snapshot = await getDocs(q);
+    let requirements = snapshot.docs.map((docSnap: DocumentSnapshot) => {
+      // Explicitly cast data after ensuring it's not undefined (though .data() on QueryDocumentSnapshot is not undefined)
+      const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
+      return { id: docSnap.id, ...data } as PatientRequirementInstance;
+    });
+
+    // Post-fetch filtering for instruction statuses and due times
+    if (
+      filters?.instructionStatuses &&
+      filters.instructionStatuses.length > 0
+    ) {
+      requirements = requirements.filter((req) =>
+        req.instructions.some((instr) =>
+          filters.instructionStatuses!.includes(instr.status)
+        )
+      );
+    }
+
+    if (filters?.dueBefore) {
+      const dueBeforeMillis = filters.dueBefore.toMillis();
+      requirements = requirements.filter((req) =>
+        req.instructions.some(
+          (instr) => instr.dueTime.toMillis() < dueBeforeMillis
+        )
+      );
+    }
+
+    if (filters?.dueAfter) {
+      const dueAfterMillis = filters.dueAfter.toMillis();
+      requirements = requirements.filter((req) =>
+        req.instructions.some(
+          (instr) => instr.dueTime.toMillis() > dueAfterMillis
+        )
+      );
+    }
+
+    const newLastVisible = snapshot.docs[snapshot.docs.length - 1] || null;
+
+    return { requirements, lastDoc: newLastVisible };
+  }
+
+  /**
+   * Marks a specific instruction within a PatientRequirementInstance as ACTION_TAKEN.
+   * If all instructions are actioned, updates the overallStatus of the instance.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance.
+   * @param instructionId - The ID of the instruction to complete.
+   * @returns The updated PatientRequirementInstance.
+   * @throws Error if the instance or instruction is not found, or if the instruction is not in a completable state.
+   */
+  async completeInstruction(
+    patientId: string,
+    instanceId: string,
+    instructionId: string
+  ): Promise<PatientRequirementInstance> {
+    const instanceRef = this.getPatientRequirementDocRef(patientId, instanceId);
+    const instanceSnap = await getDoc(instanceRef); // Simplified: getDoc without explicit generic here
+
+    if (!instanceSnap.exists()) {
+      throw new Error(
+        `PatientRequirementInstance ${instanceId} not found for patient ${patientId}.`
+      );
+    }
+
+    // Explicitly cast data after exists check
+    const instanceData = instanceSnap.data() as Omit<
+      PatientRequirementInstance,
+      "id"
+    >;
+    const instance = { id: instanceSnap.id, ...instanceData };
+
+    const instructionIndex = instance.instructions.findIndex(
+      (instr) => instr.instructionId === instructionId
+    );
+
+    if (instructionIndex === -1) {
+      throw new Error(
+        `Instruction ${instructionId} not found in instance ${instanceId}.`
+      );
+    }
+
+    const instructionToUpdate = instance.instructions[instructionIndex];
+
+    // Date enforcement: reject premature completions outside actionable window
+    const currentTime = Timestamp.now();
+    const dueTime = instructionToUpdate.dueTime;
+    if (dueTime) {
+      const dueTimeMs =
+        typeof dueTime === "number"
+          ? dueTime
+          : typeof (dueTime as any).toMillis === "function"
+            ? (dueTime as any).toMillis()
+            : 0;
+      if (dueTimeMs > 0) {
+        const actionableWindowHours =
+          (instructionToUpdate as any).actionableWindow || 24;
+        const windowStartMs =
+          dueTimeMs - actionableWindowHours * 60 * 60 * 1000;
+        if (currentTime.toMillis() < windowStartMs) {
+          throw new Error(
+            `Instruction ${instructionId} cannot be completed yet. ` +
+              `Actionable window starts at ${new Date(windowStartMs).toISOString()}.`
+          );
+        }
+      }
+    }
+
+    // Allow completion if it's PENDING_NOTIFICATION, ACTION_DUE, or even MISSED (if policy allows late completion)
+    if (
+      instructionToUpdate.status !==
+        PatientInstructionStatus.PENDING_NOTIFICATION &&
+      instructionToUpdate.status !== PatientInstructionStatus.ACTION_DUE &&
+      instructionToUpdate.status !== PatientInstructionStatus.MISSED
+    ) {
+      // If already ACTION_TAKEN or CANCELLED, do nothing or throw specific error
+      if (
+        instructionToUpdate.status === PatientInstructionStatus.ACTION_TAKEN
+      ) {
+        console.warn(
+          `Instruction ${instructionId} is already marked as ACTION_TAKEN.`
+        );
+        return instance as PatientRequirementInstance; // Ensure return type matches
+      }
+      throw new Error(
+        `Instruction ${instructionId} is in status ${instructionToUpdate.status} and cannot be marked as completed.`
+      );
+    }
+
+    const now = Timestamp.now();
+    const updatedInstructions = [...instance.instructions];
+    updatedInstructions[instructionIndex] = {
+      ...instructionToUpdate,
+      status: PatientInstructionStatus.ACTION_TAKEN,
+      actionTakenAt: now,
+      updatedAt: now,
+    };
+
+    // Check if all instructions are now ACTION_TAKEN
+    const allActionTaken = updatedInstructions.every(
+      (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
+    );
+
+    let newOverallStatus = instance.overallStatus;
+    if (allActionTaken) {
+      newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
+    } else if (
+      updatedInstructions.some(
+        (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
+      )
+    ) {
+      // If some are taken, but not all, and it was previously just ACTIVE
+      newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
+    }
+
+    const updatePayload: { [key: string]: any } = {
+      // Using a general type for updateDoc payload
+      instructions: updatedInstructions,
+      updatedAt: now,
+    };
+
+    if (newOverallStatus !== instance.overallStatus) {
+      updatePayload.overallStatus = newOverallStatus;
+    }
+
+    await updateDoc(instanceRef, updatePayload);
+
+    // Construct the returned object accurately
+    return {
+      ...instance,
+      instructions: updatedInstructions,
+      updatedAt: now,
+      overallStatus: newOverallStatus,
+    } as PatientRequirementInstance;
+  }
+
+  // Note: As per the request, full CRUD (create, direct update of instance, delete) is not part of this light service,
+  // as those will be handled by Cloud Functions reacting to appointment lifecycle events.
+}