@blackcode_sa/metaestetics-api 1.5.28 → 1.5.30

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.5.28",
+  "version": "1.5.30",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -83,6 +83,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@types/jest": "^29.5.14",
+    "@types/mailgun-js": "^0.22.18",
     "@types/node": "^20.17.13",
     "@types/react": "~18.3.12",
     "expo-crypto": "^14.0.0",

package/src/admin/aggregation/README.md

@@ -0,0 +1,79 @@
+# Data Aggregation Services
+
+This directory contains services responsible for maintaining data consistency across related Firestore collections. These aggregation services are typically used by Cloud Functions that react to document changes (create/update/delete operations).
+
+## Purpose
+
+When a document is created, updated, or deleted in one collection, related documents in other collections often need to be updated to maintain data consistency and support efficient querying. For example:
+
+- When a practitioner is updated, their information needs to be updated in associated clinics
+- When a procedure is added, summaries need to be added to both practitioner and clinic documents
+- When a clinic is deleted, related calendar events need to be canceled
+
+Rather than embedding this logic in the main service classes, these aggregation services keep the concerns separate and can be independently triggered by Cloud Functions.
+
+## Design Pattern
+
+Each aggregation service:
+
+1. Handles a specific domain entity (clinic, practitioner, procedure, etc.)
+2. Contains methods organized by event type (creation, update, deletion)
+3. Focuses solely on updating related collections
+4. Uses transactions where appropriate to ensure consistency
+
+## Available Aggregation Services
+
+- `ClinicAggregationService`: Handles clinic-related aggregations
+- `PractitionerAggregationService`: Handles practitioner-related aggregations
+- `ProcedureAggregationService`: Handles procedure-related aggregations
+- `PatientAggregationService`: Handles patient-related aggregations
+
+## Implementation Notes
+
+- These services are for admin/internal use only
+- They operate with admin Firestore privileges
+- They are designed for use by Cloud Functions, not directly by client applications
+- They include detailed logging for monitoring and debugging
+
+## Example Usage
+
+In a Cloud Function:
+
+```typescript
+exports.onPractitionerUpdate = functions.firestore
+  .document('practitioners/{practitionerId}')
+  .onUpdate(async (change, context) => {
+    const beforeData = change.before.data();
+    const afterData = change.after.data();
+    const practitionerId = context.params.practitionerId;
+
+    // Only run aggregation if specific fields changed
+    if (beforeData.basicInfo.firstName !== afterData.basicInfo.firstName ||
+        beforeData.basicInfo.lastName !== afterData.basicInfo.lastName ||
+        beforeData.basicInfo.profileImageUrl !== afterData.basicInfo.profileImageUrl) {
+
+      const aggregationService = new PractitionerAggregationService();
+
+      // Build doctorInfo object from updated data
+      const doctorInfo = {
+        id: practitionerId,
+        name: `${afterData.basicInfo.firstName} ${afterData.basicInfo.lastName}`,
+        photo: afterData.basicInfo.profileImageUrl || '',
+        // other fields...
+      };
+
+      // Update practitioner info in all related clinics
+      await aggregationService.updatePractitionerInfoInClinics(
+        afterData.clinics,
+        doctorInfo
+      );
+
+      // Update practitioner info in all related procedures
+      await aggregationService.updatePractitionerInfoInProcedures(
+        afterData.procedures,
+        doctorInfo
+      );
+    }
+  });
+</rewritten_file>
+```

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

@@ -0,0 +1,52 @@
+# Clinic Aggregation Service (Admin)
+
+This service centralizes the logic for updating aggregated data in various Firestore collections _when a clinic is created, updated, or deleted_. It is designed primarily for use by Cloud Functions triggered by changes in the `clinics` collection.
+
+## `ClinicAggregationService` Class
+
+### Constructor
+
+```typescript
+constructor(firestore?: admin.firestore.Firestore)
+```
+
+Initializes the service with an Admin Firestore instance. Uses the default instance if none is provided.
+
+### Methods Triggered by Clinic **Creation**
+
+- **`addClinicToClinicGroup(clinicGroupId: string, clinicInfo: ClinicInfo): Promise<void>`**
+  - Adds the `clinicInfo` object and `clinicId` to the `clinicsInfo` and `clinicIds` arrays respectively in the specified parent `ClinicGroup` document.
+
+### Methods Triggered by Clinic **Update**
+
+- **`updateClinicInfoInPractitioners(practitionerIds: string[], clinicInfo: ClinicInfo): Promise<void>`**
+  - Updates the aggregated `clinicsInfo` array within multiple `Practitioner` documents.
+  - Uses a batch write to first remove the old `ClinicInfo` (matching by `id`) and then add the updated `clinicInfo`.
+- **`updateClinicInfoInProcedures(procedureIds: string[], clinicInfo: ClinicInfo): Promise<void>`**
+  - Updates the embedded `clinicInfo` object within multiple `Procedure` documents associated with the updated clinic.
+- **`updateClinicInfoInClinicGroup(clinicGroupId: string, clinicInfo: ClinicInfo): Promise<void>`**
+  - Updates the `clinicsInfo` array within the parent `ClinicGroup` document.
+  - Uses a batch write to first remove the old `ClinicInfo` (matching by `id`) and then add the updated `clinicInfo`.
+- **`updateClinicInfoInPatients(patientIds: string[], clinicInfo: ClinicInfo, clinicIsActive: boolean): Promise<void>`**
+  - Currently logs a warning as the `PatientProfile` doesn't store full `ClinicInfo`.
+  - Intended place for logic if patient records need updates based on clinic changes (e.g., clinic deactivation).
+- **`updateClinicLocationInCalendarEvents(clinicId: string, newLocation: ClinicLocation): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `clinicId`.
+  - Updates the `eventLocation` field in these calendar events with the `newLocation`.
+- **`updateClinicInfoInCalendarEvents(clinicId: string, clinicInfo: ClinicInfo): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `clinicId`.
+  - Updates the embedded `clinicInfo` object in these calendar events.
+
+### Methods Triggered by Clinic **Deletion**
+
+- **`removeClinicFromPractitioners(practitionerIds: string[], clinicId: string): Promise<void>`**
+  - Removes the `clinicId` from the `clinicIds` array and the corresponding `ClinicInfo` object (matching by `id`) from the `clinicsInfo` array in multiple `Practitioner` documents.
+- **`inactivateProceduresForClinic(procedureIds: string[]): Promise<void>`**
+  - Sets the `isActive` flag to `false` for multiple `Procedure` documents associated with the deleted clinic.
+- **`removeClinicFromClinicGroup(clinicGroupId: string, clinicId: string): Promise<void>`**
+  - Removes the `clinicId` from the `clinicIds` array and the corresponding `ClinicInfo` object (matching by `id`) from the `clinicsInfo` array in the parent `ClinicGroup` document.
+- **`removeClinicFromPatients(patientIds: string[], clinicId: string): Promise<void>`**
+  - Removes the `clinicId` from the `clinicIds` array in multiple `Patient` documents.
+- **`cancelUpcomingCalendarEventsForClinic(clinicId: string): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `clinicId`.
+  - Sets the `status` of these events to `CANCELED` and adds a `cancelReason`.