@blackcode_sa/metaestetics-api 1.12.8 → 1.12.11

package/package.json

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

package/src/admin/aggregation/forms/README.md

@@ -0,0 +1,13 @@
+# Forms Aggregation Service
+
+This directory contains services responsible for handling data aggregation and side effects related to form submissions within the system.
+
+## FilledFormsAggregationService
+
+`FilledFormsAggregationService` is triggered when a `FilledDocument` is created, updated, or deleted. Its primary responsibility is to keep the corresponding `Appointment` document synchronized with the state of its associated forms.
+
+### Core Functions:
+
+- **`handleFilledFormCreateOrUpdate`**: When a form is filled or updated, this function updates the `linkedForms` array on the parent `Appointment` document. It fetches the correct document template (including the specific version) to retrieve the form's `title` and other metadata, ensuring the appointment has up-to-date information about the form's status, path, and title.
+- **`handleFilledFormDelete`**: When a filled form is deleted, this function removes the corresponding entry from the `linkedForms` and `linkedFormIds` arrays on the `Appointment` document.
+- **`handleRequiredUserFormCreate`**: When a new form that is marked as `isRequired` is created for a user, this function adds the form's ID to the `pendingUserFormsIds` array on the `Appointment`, helping track incomplete required forms.

package/src/admin/aggregation/forms/filled-forms.aggregation.service.ts

@@ -1,17 +1,13 @@
-import * as admin from "firebase-admin";
+import * as admin from 'firebase-admin';
 import {
   FilledDocument,
   FilledDocumentStatus,
   USER_FORMS_SUBCOLLECTION,
   DOCTOR_FORMS_SUBCOLLECTION,
-} from "../../../types/documentation-templates";
-import {
-  Appointment,
-  LinkedFormInfo,
-  APPOINTMENTS_COLLECTION,
-} from "../../../types/appointment";
-import { Logger } from "../../logger";
-import { Timestamp } from "firebase/firestore";
+} from '../../../types/documentation-templates';
+import { Appointment, LinkedFormInfo, APPOINTMENTS_COLLECTION } from '../../../types/appointment';
+import { Logger } from '../../logger';
+import { Timestamp } from 'firebase/firestore';
 
 /**
  * @class FilledFormsAggregationService
@@ -27,7 +23,7 @@ export class FilledFormsAggregationService {
    */
   constructor(firestore?: admin.firestore.Firestore) {
     this.db = firestore || admin.firestore();
-    Logger.info("[FilledFormsAggregationService] Initialized");
+    Logger.info('[FilledFormsAggregationService] Initialized');
   }
 
   /**
@@ -36,11 +32,9 @@ export class FilledFormsAggregationService {
    * @param filledDocument The filled document that was created or updated.
    * @returns {Promise<void>}
    */
-  async handleFilledFormCreateOrUpdate(
-    filledDocument: FilledDocument
-  ): Promise<void> {
+  async handleFilledFormCreateOrUpdate(filledDocument: FilledDocument): Promise<void> {
     Logger.info(
-      `[FilledFormsAggregationService] Handling CREATE/UPDATE for filled form: ${filledDocument.id}, appointment: ${filledDocument.appointmentId}`
+      `[FilledFormsAggregationService] Handling CREATE/UPDATE for filled form: ${filledDocument.id}, appointment: ${filledDocument.appointmentId}`,
     );
 
     try {
@@ -52,11 +46,48 @@ export class FilledFormsAggregationService {
       const appointmentDoc = await appointmentRef.get();
       if (!appointmentDoc.exists) {
         Logger.error(
-          `[FilledFormsAggregationService] Appointment ${filledDocument.appointmentId} not found.`
+          `[FilledFormsAggregationService] Appointment ${filledDocument.appointmentId} not found.`,
         );
         return;
       }
 
+      // Fetch the document template to get the title, with fallbacks.
+      let templateData: admin.firestore.DocumentData | undefined;
+      const templateRef = this.db
+        .collection('documentation-templates')
+        .doc(filledDocument.templateId);
+      const templateDoc = await templateRef.get();
+
+      if (templateDoc.exists) {
+        const currentTemplateData = templateDoc.data();
+        if (currentTemplateData && currentTemplateData.version === filledDocument.templateVersion) {
+          // The requested version is the latest one.
+          templateData = currentTemplateData;
+        } else {
+          // The requested version is an older one, look in the 'versions' subcollection.
+          const versionRef = templateRef
+            .collection('versions')
+            .doc(filledDocument.templateVersion.toString());
+          const versionDoc = await versionRef.get();
+
+          if (versionDoc.exists) {
+            templateData = versionDoc.data();
+          } else {
+            // Fallback 1: If the specific version is not found, use the latest version as a fallback.
+            Logger.warn(
+              `[FilledFormsAggregationService] Template version ${filledDocument.templateVersion} not found for template ${filledDocument.templateId}. Falling back to the latest version.`,
+            );
+            templateData = currentTemplateData;
+          }
+        }
+      } else {
+        // This case should be rare if data is consistent, but we handle it.
+        Logger.error(
+          `[FilledFormsAggregationService] Document template ${filledDocument.templateId} not found. Cannot retrieve title.`,
+        );
+        // templateData remains undefined, will trigger the final fallback for the title.
+      }
+
       const appointment = appointmentDoc.data() as Appointment;
 
       // 2. Prepare the LinkedFormInfo object
@@ -68,9 +99,7 @@ export class FilledFormsAggregationService {
         formId: filledDocument.id,
         templateId: filledDocument.templateId,
         templateVersion: filledDocument.templateVersion,
-        title: filledDocument.isUserForm
-          ? "User Form" // Default title if not available
-          : "Doctor Form", // Default title if not available
+        title: templateData?.title || (filledDocument.isUserForm ? 'User Form' : 'Doctor Form'),
         isUserForm: filledDocument.isUserForm,
         isRequired: filledDocument.isRequired,
         status: filledDocument.status,
@@ -81,7 +110,7 @@ export class FilledFormsAggregationService {
       if (filledDocument.updatedAt) {
         // Convert to admin.firestore.Timestamp to ensure compatibility
         linkedFormInfo.submittedAt = admin.firestore.Timestamp.fromMillis(
-          filledDocument.updatedAt
+          filledDocument.updatedAt,
         ) as unknown as Timestamp;
       }
 
@@ -90,7 +119,7 @@ export class FilledFormsAggregationService {
         filledDocument.status === FilledDocumentStatus.SIGNED
       ) {
         linkedFormInfo.completedAt = admin.firestore.Timestamp.fromMillis(
-          filledDocument.updatedAt
+          filledDocument.updatedAt,
         ) as unknown as Timestamp;
       }
 
@@ -101,7 +130,7 @@ export class FilledFormsAggregationService {
       if (appointment.linkedForms && appointment.linkedForms.length > 0) {
         // Filter out any existing entries for this form ID to prevent duplicates
         updatedLinkedForms = appointment.linkedForms.filter(
-          (form) => form.formId !== filledDocument.id
+          form => form.formId !== filledDocument.id,
         );
       }
 
@@ -134,10 +163,11 @@ export class FilledFormsAggregationService {
           appointment.pendingUserFormsIds.includes(filledDocument.id)
         ) {
           // Remove the form ID from pendingUserFormsIds
-          updateData.pendingUserFormsIds =
-            admin.firestore.FieldValue.arrayRemove(filledDocument.id);
+          updateData.pendingUserFormsIds = admin.firestore.FieldValue.arrayRemove(
+            filledDocument.id,
+          );
           Logger.info(
-            `[FilledFormsAggregationService] Removing form ${filledDocument.id} from pendingUserFormsIds`
+            `[FilledFormsAggregationService] Removing form ${filledDocument.id} from pendingUserFormsIds`,
           );
         }
       }
@@ -145,12 +175,12 @@ export class FilledFormsAggregationService {
       // 6. Update the appointment
       await appointmentRef.update(updateData);
       Logger.info(
-        `[FilledFormsAggregationService] Successfully updated appointment ${filledDocument.appointmentId} with form info for ${filledDocument.id}`
+        `[FilledFormsAggregationService] Successfully updated appointment ${filledDocument.appointmentId} with form info for ${filledDocument.id}`,
       );
     } catch (error) {
       Logger.error(
         `[FilledFormsAggregationService] Error updating appointment for filled form ${filledDocument.id}:`,
-        error
+        error,
       );
       throw error;
     }
@@ -164,7 +194,7 @@ export class FilledFormsAggregationService {
    */
   async handleFilledFormDelete(filledDocument: FilledDocument): Promise<void> {
     Logger.info(
-      `[FilledFormsAggregationService] Handling DELETE for filled form: ${filledDocument.id}, appointment: ${filledDocument.appointmentId}`
+      `[FilledFormsAggregationService] Handling DELETE for filled form: ${filledDocument.id}, appointment: ${filledDocument.appointmentId}`,
     );
 
     try {
@@ -176,7 +206,7 @@ export class FilledFormsAggregationService {
       const appointmentDoc = await appointmentRef.get();
       if (!appointmentDoc.exists) {
         Logger.error(
-          `[FilledFormsAggregationService] Appointment ${filledDocument.appointmentId} not found.`
+          `[FilledFormsAggregationService] Appointment ${filledDocument.appointmentId} not found.`,
         );
         return;
       }
@@ -189,23 +219,17 @@ export class FilledFormsAggregationService {
       // 3. Remove the form from linkedForms if it exists
       if (appointment.linkedForms && appointment.linkedForms.length > 0) {
         const formToRemove = appointment.linkedForms.find(
-          (form) => form.formId === filledDocument.id
+          form => form.formId === filledDocument.id,
         );
 
         if (formToRemove) {
-          updateData.linkedForms =
-            admin.firestore.FieldValue.arrayRemove(formToRemove);
+          updateData.linkedForms = admin.firestore.FieldValue.arrayRemove(formToRemove);
         }
       }
 
       // 4. Remove the form ID from linkedFormIds
-      if (
-        appointment.linkedFormIds &&
-        appointment.linkedFormIds.includes(filledDocument.id)
-      ) {
-        updateData.linkedFormIds = admin.firestore.FieldValue.arrayRemove(
-          filledDocument.id
-        );
+      if (appointment.linkedFormIds && appointment.linkedFormIds.includes(filledDocument.id)) {
+        updateData.linkedFormIds = admin.firestore.FieldValue.arrayRemove(filledDocument.id);
       }
 
       // 5. For required user forms, handle pendingUserFormsIds
@@ -231,17 +255,17 @@ export class FilledFormsAggregationService {
         updateData.updatedAt = admin.firestore.FieldValue.serverTimestamp();
         await appointmentRef.update(updateData);
         Logger.info(
-          `[FilledFormsAggregationService] Successfully updated appointment ${filledDocument.appointmentId} after form deletion`
+          `[FilledFormsAggregationService] Successfully updated appointment ${filledDocument.appointmentId} after form deletion`,
         );
       } else {
         Logger.info(
-          `[FilledFormsAggregationService] No updates needed for appointment ${filledDocument.appointmentId}`
+          `[FilledFormsAggregationService] No updates needed for appointment ${filledDocument.appointmentId}`,
         );
       }
     } catch (error) {
       Logger.error(
         `[FilledFormsAggregationService] Error updating appointment after form deletion for ${filledDocument.id}:`,
-        error
+        error,
       );
       throw error;
     }
@@ -253,15 +277,13 @@ export class FilledFormsAggregationService {
    * @param filledDocument The newly created filled document.
    * @returns {Promise<void>}
    */
-  async handleRequiredUserFormCreate(
-    filledDocument: FilledDocument
-  ): Promise<void> {
+  async handleRequiredUserFormCreate(filledDocument: FilledDocument): Promise<void> {
     if (!filledDocument.isUserForm || !filledDocument.isRequired) {
       return; // Only process required user forms
     }
 
     Logger.info(
-      `[FilledFormsAggregationService] Handling new required user form creation: ${filledDocument.id}`
+      `[FilledFormsAggregationService] Handling new required user form creation: ${filledDocument.id}`,
     );
 
     try {
@@ -275,26 +297,24 @@ export class FilledFormsAggregationService {
         filledDocument.status === FilledDocumentStatus.SIGNED
       ) {
         Logger.info(
-          `[FilledFormsAggregationService] Form ${filledDocument.id} is already completed/signed, not adding to pendingUserFormsIds`
+          `[FilledFormsAggregationService] Form ${filledDocument.id} is already completed/signed, not adding to pendingUserFormsIds`,
         );
         return;
       }
 
       // Add to pendingUserFormsIds
       await appointmentRef.update({
-        pendingUserFormsIds: admin.firestore.FieldValue.arrayUnion(
-          filledDocument.id
-        ),
+        pendingUserFormsIds: admin.firestore.FieldValue.arrayUnion(filledDocument.id),
         updatedAt: admin.firestore.FieldValue.serverTimestamp(),
       });
 
       Logger.info(
-        `[FilledFormsAggregationService] Successfully added form ${filledDocument.id} to pendingUserFormsIds for appointment ${filledDocument.appointmentId}`
+        `[FilledFormsAggregationService] Successfully added form ${filledDocument.id} to pendingUserFormsIds for appointment ${filledDocument.appointmentId}`,
       );
     } catch (error) {
       Logger.error(
         `[FilledFormsAggregationService] Error handling required user form creation for ${filledDocument.id}:`,
-        error
+        error,
       );
       throw error;
     }

package/src/services/appointment/README.md

@@ -0,0 +1,17 @@
+# Appointment Service
+
+This service is responsible for managing appointments.
+
+## Methods
+
+### `countCompletedAppointments(patientId: string, clinicBranchId?: string, excludeClinic: boolean = true): Promise<number>`
+
+Counts the number of completed appointments for a given patient.
+
+- `patientId`: The ID of the patient.
+- `clinicBranchId` (optional): The ID of a clinic branch to filter by.
+- `excludeClinic` (optional, default: `true`):
+  - If `true`, it counts appointments _outside_ the specified `clinicBranchId`.
+  - If `false`, it counts appointments _only within_ the specified `clinicBranchId`.
+
+If `clinicBranchId` is not provided, it counts all completed appointments for the patient across all clinics.