@blackcode_sa/metaestetics-api 1.6.2 → 1.6.4

package/package.json

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

package/src/admin/index.ts

@@ -30,6 +30,9 @@ import { PractitionerInviteMailingService } from "./mailing/practitionerInvite/p
 // Import booking services
 import { BookingAdmin } from "./booking/booking.admin";
 
+// Import patient requirements services
+import { PatientRequirementsAdminService } from "./requirements/patient-requirements.admin.service";
+
 // Re-export types
 export type {
   Notification,
@@ -37,7 +40,6 @@ export type {
   PreRequirementNotification,
   PostRequirementNotification,
   AppointmentReminderNotification,
-  AppointmentNotification,
 } from "../types/notifications";
 
 // Re-export types needed by cloud functions
@@ -64,6 +66,7 @@ export {
   PractitionerAggregationService,
   ProcedureAggregationService,
   PatientAggregationService,
+  PatientRequirementsAdminService,
 };
 
 // Export mailing services
@@ -75,6 +78,17 @@ export { BookingAdmin };
 // Also export booking types
 export * from "./booking/booking.types";
 
+// Re-export types needed by admin services that might not be covered by general type exports
+export type {
+  PatientRequirementInstance,
+  PatientRequirementInstruction,
+} from "../types/patient/patient-requirements";
+export {
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+} from "../types/patient/patient-requirements";
+
 /**
  * Main entry point for the Admin module.
  * This module contains services and utilities intended for administrative tasks,

package/src/admin/notifications/notifications.admin.ts

@@ -56,7 +56,7 @@ export class NotificationsAdmin {
   /**
    * Ažurira status notifikacije
    */
-  private async updateNotificationStatus(
+  public async updateNotificationStatus(
     notificationId: string,
     status: NotificationStatus,
     error?: string

package/src/admin/requirements/README.md

@@ -0,0 +1,128 @@
+# Patient Requirements Admin Service (`patient-requirements.admin.service.ts`)
+
+## Overview
+
+The `PatientRequirementsAdminService` is a backend service responsible for managing administrative tasks related to `PatientRequirementInstance` documents, primarily focusing on the lifecycle of associated patient notifications. This service is designed to be primarily invoked by Cloud Functions that trigger on Create, Update, and Delete events of `PatientRequirementInstance` documents in Firestore.
+
+It ensures that patients receive timely notifications for instructions they need to follow before an appointment and that these notifications are appropriately updated or cancelled if the appointment or requirement details change.
+
+## Core Dependencies
+
+- **Firebase Admin SDK**: For interacting with Firestore.
+- **`NotificationsAdmin` Service**: For creating, fetching, and updating notification documents.
+- **Shared Types**: Uses types defined in `Api/src/types/` for `PatientRequirementInstance`, `PatientInstruction`, `Notification`, `PatientProfile`, etc., ensuring consistency across the application. This includes using client-side `Timestamp` types (`@firebase/firestore.Timestamp`) for data stored in Firestore documents that are also accessed by the client.
+
+## Methods
+
+### 1. `constructor(firestore?: admin.firestore.Firestore)`
+
+- **Purpose**: Initializes the service.
+- **Parameters**:
+  - `firestore` (optional): An instance of `admin.firestore.Firestore`. If not provided, it initializes a new default instance.
+- **Core Logic**:
+  1.  Sets up the Firestore database connection (`this.db`).
+  2.  Initializes an instance of the `NotificationsAdmin` service (`this.notificationsAdmin`), passing the Firestore instance to it.
+
+### 2. `async processRequirementInstanceAndScheduleNotifications(patientId: string, instance: PatientRequirementInstance, previousInstanceData?: PatientRequirementInstance)`
+
+- **Purpose**: This is the primary method for handling the creation and updates of a `PatientRequirementInstance`. It iterates through the instructions within the instance, schedules new notifications, cancels outdated ones, and updates the instruction statuses and notification IDs within the `PatientRequirementInstance` document.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient to whom the requirement instance belongs.
+  - `instance: PatientRequirementInstance`: The current (new or updated) data of the patient requirement instance.
+  - `previousInstanceData?: PatientRequirementInstance` (optional): The state of the instance _before_ the current change. This is crucial for determining if due times have changed or if instructions were cancelled/reactivated, necessitating changes to existing notifications.
+- **Core Logic Flow**:
+  1.  **Fetch Patient Expo Tokens**: Retrieves the patient's Expo push notification tokens from their `PatientProfile`. If no tokens are found, notification scheduling for that patient is skipped.
+  2.  **Iterate Through Instructions**: Loops through each `PatientRequirementInstruction` in the `instance.instructions` array.
+      - A copy of the instructions array (`updatedInstructions`) is made to track changes without mutating the input directly.
+  3.  **Handle Cancelled/Superseded Instances/Instructions**:
+      - If the overall `instance.overallStatus` indicates a cancelled appointment or a superseded reschedule, or if an individual `currentInstruction.status` is `CANCELLED`:
+        - If the instruction had an existing `notificationId`, calls `this.notificationsAdmin.updateNotificationStatus()` to set the notification's status to `CANCELLED`.
+        - Updates the `currentInstruction`'s `notificationId` to `undefined` and its `status` to `CANCELLED`.
+        - Marks that `instructionUpdatesMade` is `true`.
+  4.  **Handle Reschedules/Reactivations for Existing Notifications**:
+      - Compares `currentInstruction` with `previousInstruction` (if available).
+      - Determines if `dueTimeChanged` or if the instruction `wasPreviouslyCancelledAndNowActive`.
+      - If either is true AND the `currentInstruction` has a `notificationId` (meaning an old notification exists):
+        - Cancels the old notification using `this.notificationsAdmin.updateNotificationStatus()`.
+        - Clears `currentInstruction.notificationId`.
+        - Marks `instructionUpdatesMade` as `true`.
+  5.  **Schedule New Notifications**:
+      - Checks if a notification `shouldSchedule` for the `currentInstruction`:
+        - Instruction status must be `PENDING_NOTIFICATION`.
+        - No existing `notificationId`.
+        - `dueTime` must be in the future.
+        - Patient must have Expo tokens.
+      - If `shouldSchedule` is true:
+        - Constructs a `notificationPayload` for a `RequirementInstructionDueNotification`.
+        - Calls `this.notificationsAdmin.createNotification()` to create the notification document.
+        - Updates `currentInstruction` with the new `notificationId` and ensures its status is `PENDING_NOTIFICATION`.
+        - Marks `instructionUpdatesMade` as `true`.
+  6.  **Update Firestore Document**:
+      - If `instructionUpdatesMade` is `true` (meaning any instruction's notification details or status changed):
+        - Updates the `PatientRequirementInstance` document in Firestore with the `updatedInstructions` array and sets its `updatedAt` timestamp.
+        - Ensures all `updatedAt` (and other Timestamp fields) within `updatedInstructions` and for the main instance are converted to `FirebaseClientTimestamp` for compatibility with shared types.
+- **Usage Context**:
+  - Triggered by a Cloud Function on **create** of a `PatientRequirementInstance`.
+  - Triggered by a Cloud Function on **update** of a `PatientRequirementInstance`. The Cloud Function should provide both the new and previous data of the instance.
+
+### 3. `async cancelAllNotificationsForInstance(instance: PatientRequirementInstance)`
+
+- **Purpose**: To cancel all _pending_ notifications associated with a given `PatientRequirementInstance`. This is typically used when an entire instance is hard-deleted or unequivocally cancelled in a way not covered by status changes processed by `processRequirementInstanceAndScheduleNotifications`.
+- **Parameters**:
+  - `instance: PatientRequirementInstance`: The requirement instance whose notifications need to be cancelled.
+- **Core Logic Flow**:
+  1.  Iterates through each instruction in `instance.instructions`.
+  2.  If an instruction has a `notificationId`:
+      - Fetches the notification using `this.notificationsAdmin.getNotification()`.
+      - If the notification exists and its status is `PENDING`:
+        - Calls `this.notificationsAdmin.updateNotificationStatus()` to set its status to `CANCELLED`.
+- **Usage Context**:
+  - Triggered by a Cloud Function on **delete** of a `PatientRequirementInstance`.
+  - Can also be invoked if an instance's overall status changes to a terminal "cancelled" state that requires immediate cessation of all related pending notifications.
+
+### 4. `async updateMissedInstructions(patientId: string, instanceId: string)`
+
+- **Purpose**: (Optional utility, typically for a cron job) Scans instructions within a specific `PatientRequirementInstance` that are past their `dueTime` but have not yet been actioned (i.e., status is `PENDING_NOTIFICATION` or `ACTION_DUE`). It updates their status to `MISSED`.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient.
+  - `instanceId: string`: The ID of the `PatientRequirementInstance` to check.
+- **Core Logic Flow**:
+  1.  Fetches the specified `PatientRequirementInstance` document.
+  2.  If not found, logs a warning and exits.
+  3.  Iterates through each instruction in the instance.
+  4.  If an instruction's `dueTime` is in the past AND its status is `PENDING_NOTIFICATION` or `ACTION_DUE`:
+      - Updates the instruction's `status` to `MISSED`.
+      - Sets the instruction's `updatedAt` timestamp (converted to `FirebaseClientTimestamp`).
+      - Marks that `changesMade` is `true`.
+  5.  If `changesMade` is `true`:
+      - Updates the `PatientRequirementInstance` document in Firestore with the modified instructions and sets its main `updatedAt` timestamp (converted to `FirebaseClientTimestamp`).
+- **Usage Context**:
+  - Intended to be called by a scheduled Cloud Function (e.g., a daily cron job) to perform cleanup and status updates for instructions that were not completed by their due date.
+
+### 5. `async updateOverallInstanceStatus(patientId: string, instanceId: string)`
+
+- **Purpose**: Calculates and updates the `overallStatus` of a `PatientRequirementInstance` based on the collective statuses of its individual, non-cancelled instructions. This helps reflect the true completion state of the entire requirement set.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient to whom the requirement instance belongs.
+  - `instanceId: string`: The ID of the `PatientRequirementInstance` to update.
+- **Core Logic Flow**:
+  1.  **Fetch Instance**: Retrieves the specified `PatientRequirementInstance`.
+  2.  **Check Terminal States**: If the current `instance.overallStatus` is already `CANCELLED_APPOINTMENT`, `SUPERSEDED_RESCHEDULE`, or `FAILED_TO_PROCESS`, the function logs this and exits, as these are considered final states not to be overridden by this logic.
+  3.  **Handle No Active Instructions**: Filters out any instructions with a status of `CANCELLED`. If no non-cancelled instructions remain:
+      - Sets the `overallStatus` to `ACTIVE` (if not already) and updates Firestore. This acts as a default if an instance becomes empty of actionable items.
+  4.  **Check for Pending/Due Instructions**: Iterates through the non-cancelled instructions. If any instruction has a status of `PENDING_NOTIFICATION` or `ACTION_DUE`:
+      - The `newOverallStatus` is determined to be `ACTIVE`.
+  5.  **All Instructions Resolved**: If no instructions are `PENDING_NOTIFICATION` or `ACTION_DUE` (meaning all non-cancelled instructions are in a "resolved" state: `ACTION_TAKEN`, `MISSED`, or `SKIPPED`):
+      - Counts `effectivelyCompletedCount` (non-cancelled instructions that are `ACTION_TAKEN` or `SKIPPED`).
+      - Calculates `completionPercentage = (effectivelyCompletedCount / totalNonCancelledInstructions) * 100`.
+      - If `completionPercentage === 100%`, `newOverallStatus` is `ALL_INSTRUCTIONS_MET`.
+      - Else if `completionPercentage >= 60%`, `newOverallStatus` is `PARTIALLY_COMPLETED`.
+      - Else (`completionPercentage < 60%`), `newOverallStatus` is `FAILED_TO_PROCESS`.
+  6.  **Update Firestore**: If the calculated `newOverallStatus` is different from the `instance.overallStatus` currently in Firestore, it updates the document with the new status and the current timestamp (converted to `FirebaseClientTimestamp`).
+- **Usage Context**:
+  - Typically called by a Cloud Function triggered on **update** of a `PatientRequirementInstance`, ideally after `processRequirementInstanceAndScheduleNotifications` (or any other logic that might modify individual instruction statuses) has completed. This ensures the `overallStatus` accurately reflects the latest state of the instructions.
+  - It helps maintain data integrity and provides a clear, high-level status for the entire set of requirements.
+
+## Timestamp Handling
+
+A key aspect of this service is the correct handling of Firestore Timestamps. Since the shared type definitions (e.g., for `PatientRequirementInstruction`) expect Timestamps compatible with the client-side Firebase SDK (`@firebase/firestore.Timestamp`), any Timestamps generated by the Admin SDK (e.g., `admin.firestore.Timestamp.now()`) must be converted to `new FirebaseClientTimestamp(adminTimestamp.seconds, adminTimestamp.nanoseconds)` before being written back to Firestore as part of these shared types. This ensures type consistency across the backend (admin) and frontend/shared type definitions.

package/src/admin/requirements/patient-requirements.admin.service.ts

@@ -0,0 +1,482 @@
+import * as admin from "firebase-admin";
+// Import client-side Timestamp for type compatibility with shared types
+import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
+import {
+  PatientRequirementInstance,
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PatientRequirementInstruction,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+} from "../../types/patient/patient-requirements";
+import {
+  NotificationType,
+  RequirementInstructionDueNotification,
+  NOTIFICATIONS_COLLECTION,
+  NotificationStatus,
+} from "../../types/notifications";
+import { PatientProfile, PATIENTS_COLLECTION } from "../../types/patient";
+import { UserRole } from "../../types"; // Assuming UserRole is in the main types index
+import { NotificationsAdmin } from "../notifications/notifications.admin";
+
+/**
+ * @class PatientRequirementsAdminService
+ * @description Handles administrative tasks for patient requirement instances, primarily managing associated notifications.
+ * This service is intended to be used by Cloud Functions triggered by changes to PatientRequirementInstance documents.
+ */
+export class PatientRequirementsAdminService {
+  private db: admin.firestore.Firestore;
+  private notificationsAdmin: NotificationsAdmin;
+
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    this.notificationsAdmin = new NotificationsAdmin(this.db);
+  }
+
+  /**
+   * Processes a newly created or updated PatientRequirementInstance to schedule notifications for its instructions.
+   * It will also cancel pre-existing notifications if due times have changed significantly.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instance - The PatientRequirementInstance data (either new or updated).
+   * @param previousInstanceData - Optional. The previous state of the instance data if it's an update.
+   *                                 Used to determine if notifications need to be cancelled/rescheduled.
+   * @returns {Promise<void>} A promise that resolves when processing is complete.
+   */
+  async processRequirementInstanceAndScheduleNotifications(
+    patientId: string,
+    instance: PatientRequirementInstance,
+    previousInstanceData?: PatientRequirementInstance
+  ): Promise<void> {
+    console.log(
+      `[PRA_Service] Processing requirement instance ${instance.id} for patient ${patientId}. Overall Status: ${instance.overallStatus}`
+    );
+
+    const patientProfileRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId);
+    let patientExpoTokens: string[] = [];
+
+    try {
+      const patientDoc = await patientProfileRef.get();
+      if (patientDoc.exists) {
+        const patientData = patientDoc.data() as PatientProfile;
+        patientExpoTokens = patientData.expoTokens || [];
+      }
+    } catch (error) {
+      console.error(
+        `[PRA_Service] Error fetching patient ${patientId} for expo tokens:`,
+        error
+      );
+    }
+
+    if (patientExpoTokens.length === 0) {
+      console.log(
+        `[PRA_Service] Patient ${patientId} has no expo tokens. Skipping notification creation for instance ${instance.id}.`
+      );
+    }
+    // Create a new array of instruction objects to avoid mutating the original
+    // Keep original Timestamp objects by reference
+    const updatedInstructions: PatientRequirementInstruction[] =
+      instance.instructions.map((instr) => ({ ...instr }));
+    let instructionUpdatesMade = false;
+
+    for (let i = 0; i < updatedInstructions.length; i++) {
+      let currentInstruction = updatedInstructions[i];
+      const previousInstruction = previousInstanceData?.instructions.find(
+        (pi) => pi.instructionId === currentInstruction.instructionId
+      );
+      const adminTsNow = admin.firestore.Timestamp.now();
+
+      if (
+        instance.overallStatus ===
+          PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
+        instance.overallStatus ===
+          PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
+        currentInstruction.status === PatientInstructionStatus.CANCELLED
+      ) {
+        if (currentInstruction.notificationId) {
+          console.log(
+            `[PRA_Service] Cancelling notification ${currentInstruction.notificationId} for instruction ${currentInstruction.instructionId} of instance ${instance.id}.`
+          );
+          await this.notificationsAdmin.updateNotificationStatus(
+            currentInstruction.notificationId,
+            NotificationStatus.CANCELLED
+          );
+          currentInstruction = {
+            ...currentInstruction,
+            notificationId: undefined,
+            status: PatientInstructionStatus.CANCELLED,
+            updatedAt: new FirebaseClientTimestamp(
+              adminTsNow.seconds,
+              adminTsNow.nanoseconds
+            ),
+          };
+          updatedInstructions[i] = currentInstruction;
+          instructionUpdatesMade = true;
+        }
+        continue;
+      }
+
+      const dueTimeChanged =
+        previousInstruction &&
+        currentInstruction.dueTime && // Ensure dueTime exists
+        previousInstruction.dueTime.toMillis() !==
+          currentInstruction.dueTime.toMillis();
+
+      // Simplified: if previous was CANCELLED, and we are in this part of the code,
+      // it means currentInstruction.status is NOT CANCELLED (i.e., it's active).
+      const wasPreviouslyCancelledAndNowActive =
+        previousInstruction &&
+        previousInstruction.status === PatientInstructionStatus.CANCELLED;
+
+      if (
+        previousInstruction &&
+        (dueTimeChanged || wasPreviouslyCancelledAndNowActive) && // Use the simplified variable
+        currentInstruction.notificationId
+      ) {
+        console.log(
+          `[PRA_Service] Due time changed or instruction reactivated for ${currentInstruction.instructionId}. Cancelling old notification ${currentInstruction.notificationId}.`
+        );
+        await this.notificationsAdmin.updateNotificationStatus(
+          currentInstruction.notificationId,
+          NotificationStatus.CANCELLED
+        );
+        currentInstruction = {
+          ...currentInstruction,
+          notificationId: undefined,
+          updatedAt: new FirebaseClientTimestamp(
+            adminTsNow.seconds,
+            adminTsNow.nanoseconds
+          ),
+        };
+        updatedInstructions[i] = currentInstruction;
+        instructionUpdatesMade = true;
+      }
+
+      const shouldSchedule =
+        currentInstruction.dueTime && // Ensure dueTime exists
+        currentInstruction.status ===
+          PatientInstructionStatus.PENDING_NOTIFICATION &&
+        !currentInstruction.notificationId &&
+        currentInstruction.dueTime.toMillis() > adminTsNow.toMillis() &&
+        patientExpoTokens.length > 0;
+
+      if (shouldSchedule) {
+        console.log(
+          `[PRA_Service] Scheduling notification for instruction ${
+            currentInstruction.instructionId
+          } of instance ${
+            instance.id
+          } at ${currentInstruction.dueTime.toDate()}.`
+        );
+
+        const notificationPayload: Omit<
+          RequirementInstructionDueNotification,
+          "id" | "createdAt" | "updatedAt" | "status" | "isRead"
+        > = {
+          userId: patientId,
+          userRole: UserRole.PATIENT,
+          notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE,
+          notificationTime: currentInstruction.dueTime, // This is a Firestore Timestamp
+          notificationTokens: patientExpoTokens,
+          title: `Reminder: ${instance.requirementName}`,
+          body: currentInstruction.instructionText,
+          appointmentId: instance.appointmentId,
+          patientRequirementInstanceId: instance.id,
+          instructionId: currentInstruction.instructionId,
+          originalRequirementId: instance.originalRequirementId,
+        };
+
+        try {
+          const createdNotificationId =
+            await this.notificationsAdmin.createNotification(
+              notificationPayload as any
+            );
+          currentInstruction = {
+            ...currentInstruction,
+            notificationId: createdNotificationId,
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            updatedAt: new FirebaseClientTimestamp(
+              adminTsNow.seconds,
+              adminTsNow.nanoseconds
+            ),
+          };
+          updatedInstructions[i] = currentInstruction;
+          instructionUpdatesMade = true;
+        } catch (error) {
+          console.error(
+            `[PRA_Service] Failed to create notification for instruction ${currentInstruction.instructionId}:`,
+            error
+          );
+        }
+      }
+    }
+
+    if (instructionUpdatesMade) {
+      console.log(
+        `[PRA_Service] Updating instructions array for instance ${instance.id} on patient ${patientId}.`
+      );
+      const instanceDocRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(patientId)
+        .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+        .doc(instance.id);
+
+      const finalAdminTsNow = admin.firestore.Timestamp.now();
+      await instanceDocRef.update({
+        instructions: updatedInstructions, // Array of instructions with actual Timestamps
+        updatedAt: new FirebaseClientTimestamp(
+          finalAdminTsNow.seconds,
+          finalAdminTsNow.nanoseconds
+        ),
+      });
+    }
+  }
+
+  /**
+   * Cancels all PENDING notifications associated with a specific PatientRequirementInstance.
+   * Typically called when the instance itself is deleted or its overall status becomes CANCELLED.
+   *
+   * @param instance - The PatientRequirementInstance.
+   * @returns {Promise<void>}
+   */
+  async cancelAllNotificationsForInstance(
+    instance: PatientRequirementInstance
+  ): Promise<void> {
+    console.log(
+      `[PRA_Service] Attempting to cancel all pending notifications for instance ${instance.id}.`
+    );
+    let cancelledCount = 0;
+    for (const instruction of instance.instructions) {
+      if (instruction.notificationId) {
+        try {
+          const notification = await this.notificationsAdmin.getNotification(
+            instruction.notificationId
+          );
+          if (
+            notification &&
+            notification.status === NotificationStatus.PENDING
+          ) {
+            await this.notificationsAdmin.updateNotificationStatus(
+              instruction.notificationId,
+              NotificationStatus.CANCELLED
+            );
+            console.log(
+              `[PRA_Service] Cancelled notification ${instruction.notificationId} for instruction ${instruction.instructionId}.`
+            );
+            cancelledCount++;
+          } else if (notification) {
+            console.log(
+              `[PRA_Service] Notification ${instruction.notificationId} for instruction ${instruction.instructionId} was not pending (status: ${notification.status}). Not cancelling.`
+            );
+          }
+        } catch (error) {
+          console.error(
+            `[PRA_Service] Error cancelling notification ${instruction.notificationId}:`,
+            error
+          );
+        }
+      }
+    }
+    if (cancelledCount > 0) {
+      console.log(
+        `[PRA_Service] Cancelled ${cancelledCount} notifications for instance ${instance.id}.`
+      );
+    }
+  }
+
+  /**
+   * (Optional - For a cron job)
+   * Scans for instructions that are past their due time but not yet actioned, and updates their status to MISSED.
+   * This would typically be called by a scheduled Cloud Function.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance.
+   * @returns {Promise<void>}
+   */
+  async updateMissedInstructions(
+    patientId: string,
+    instanceId: string
+  ): Promise<void> {
+    const instanceRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId)
+      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+      .doc(instanceId);
+
+    const instanceSnap = await instanceRef.get();
+    if (!instanceSnap.exists) {
+      console.warn(
+        `[PRA_Service] Instance ${instanceId} not found during missed check for patient ${patientId}.`
+      );
+      return;
+    }
+
+    const instance = instanceSnap.data() as PatientRequirementInstance;
+    const adminNowForMissed = admin.firestore.Timestamp.now();
+
+    // Create a new array of instruction objects to avoid mutating the original
+    const updatedInstructions: PatientRequirementInstruction[] =
+      instance.instructions.map((instr) => ({ ...instr }));
+    let changesMade = false;
+
+    for (let i = 0; i < updatedInstructions.length; i++) {
+      let currentInstruction = updatedInstructions[i];
+      if (
+        currentInstruction.dueTime && // Ensure dueTime exists
+        (currentInstruction.status ===
+          PatientInstructionStatus.PENDING_NOTIFICATION ||
+          currentInstruction.status === PatientInstructionStatus.ACTION_DUE) &&
+        currentInstruction.dueTime.toMillis() < adminNowForMissed.toMillis()
+      ) {
+        currentInstruction = {
+          ...currentInstruction,
+          status: PatientInstructionStatus.MISSED,
+          updatedAt: new FirebaseClientTimestamp(
+            adminNowForMissed.seconds,
+            adminNowForMissed.nanoseconds
+          ),
+        };
+        updatedInstructions[i] = currentInstruction;
+        changesMade = true;
+        console.log(
+          `[PRA_Service] Marked instruction ${currentInstruction.instructionId} in instance ${instanceId} as MISSED.`
+        );
+      }
+    }
+
+    if (changesMade) {
+      const finalAdminNowForMissedUpdate = admin.firestore.Timestamp.now();
+      await instanceRef.update({
+        instructions: updatedInstructions, // Array of instructions with actual Timestamps
+        updatedAt: new FirebaseClientTimestamp(
+          finalAdminNowForMissedUpdate.seconds,
+          finalAdminNowForMissedUpdate.nanoseconds
+        ),
+      });
+      console.log(
+        `[PRA_Service] Updated missed instructions for instance ${instanceId}.`
+      );
+    }
+  }
+
+  /**
+   * Calculates and updates the overallStatus of a PatientRequirementInstance
+   * based on the statuses of its individual instructions.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance to update.
+   * @returns {Promise<void>} A promise that resolves when processing is complete.
+   */
+  async updateOverallInstanceStatus(
+    patientId: string,
+    instanceId: string
+  ): Promise<void> {
+    const instanceRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId)
+      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+      .doc(instanceId);
+
+    const instanceSnap = await instanceRef.get();
+    if (!instanceSnap.exists) {
+      console.warn(
+        `[PRA_Service] Instance ${instanceId} not found while trying to update overall status for patient ${patientId}.`
+      );
+      return;
+    }
+
+    const instance = instanceSnap.data() as PatientRequirementInstance;
+
+    // Do not override terminal statuses set by other processes
+    if (
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.FAILED_TO_PROCESS // Assuming FAILED_TO_PROCESS is also a terminal state set by other means if it's a hard failure.
+    ) {
+      console.log(
+        `[PRA_Service] Instance ${instanceId} has overallStatus ${instance.overallStatus}, skipping overall status update based on instruction completion logic.`
+      );
+      return;
+    }
+
+    const nonCancelledInstructions = instance.instructions.filter(
+      (instr) => instr.status !== PatientInstructionStatus.CANCELLED
+    );
+
+    if (nonCancelledInstructions.length === 0) {
+      // If all instructions are cancelled or there are no instructions.
+      // If it was previously something like ALL_INSTRUCTIONS_MET, it should revert to ACTIVE or a default.
+      if (instance.overallStatus !== PatientRequirementOverallStatus.ACTIVE) {
+        console.log(
+          `[PRA_Service] Instance ${instanceId} has no active (non-cancelled) instructions. Setting to ACTIVE.`
+        );
+        await instanceRef.update({
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          updatedAt: new FirebaseClientTimestamp(
+            admin.firestore.Timestamp.now().seconds,
+            admin.firestore.Timestamp.now().nanoseconds
+          ),
+        });
+      }
+      return;
+    }
+
+    // Check if any instruction is still pending action by the patient
+    const hasPendingOrDueInstructions = nonCancelledInstructions.some(
+      (instr) =>
+        instr.status === PatientInstructionStatus.PENDING_NOTIFICATION ||
+        instr.status === PatientInstructionStatus.ACTION_DUE
+    );
+
+    let newOverallStatus: PatientRequirementOverallStatus;
+
+    if (hasPendingOrDueInstructions) {
+      newOverallStatus = PatientRequirementOverallStatus.ACTIVE;
+    } else {
+      // All non-cancelled instructions are in a "resolved" state (ACTION_TAKEN, MISSED, SKIPPED)
+      const effectivelyCompletedCount = nonCancelledInstructions.filter(
+        (instr) =>
+          instr.status === PatientInstructionStatus.ACTION_TAKEN ||
+          instr.status === PatientInstructionStatus.SKIPPED
+      ).length;
+
+      const totalNonCancelled = nonCancelledInstructions.length;
+      const completionPercentage =
+        (effectivelyCompletedCount / totalNonCancelled) * 100;
+
+      if (completionPercentage === 100) {
+        newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
+      } else if (completionPercentage >= 60) {
+        // Changed from >60 to >=60 as per common understanding of "more than 60%" often including 60%
+        newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
+      } else {
+        // Less than 60% effectively completed (could include some MISSED ones not blocking this calculation directly)
+        // Or if all are MISSED, this would also fall here if FAILED_TO_PROCESS isn't set for other reasons.
+        // Your logic: "if less then 60% of instructions are action taken or skipped, then we move status to failed"
+        newOverallStatus = PatientRequirementOverallStatus.FAILED_TO_PROCESS;
+      }
+    }
+
+    if (newOverallStatus !== instance.overallStatus) {
+      console.log(
+        `[PRA_Service] Updating overallStatus for instance ${instanceId} from ${instance.overallStatus} to ${newOverallStatus}.`
+      );
+      const adminTsNow = admin.firestore.Timestamp.now();
+      await instanceRef.update({
+        overallStatus: newOverallStatus,
+        updatedAt: new FirebaseClientTimestamp(
+          adminTsNow.seconds,
+          adminTsNow.nanoseconds
+        ),
+      });
+    } else {
+      console.log(
+        `[PRA_Service] Calculated overallStatus ${newOverallStatus} for instance ${instanceId} is same as current. No update needed.`
+      );
+    }
+  }
+}