@blackcode_sa/metaestetics-api 1.5.29 → 1.5.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.5.29",
+  "version": "1.5.31",
   "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`.

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

@@ -0,0 +1,27 @@
+# Patient Aggregation Service (Admin)
+
+This service centralizes the logic for updating aggregated data in various Firestore collections _when patient data is updated or deleted_. It is designed primarily for use by Cloud Functions triggered by changes in the `patients` collection.
+
+**Note:** No specific aggregations are currently defined for patient _creation_ events in this service.
+
+## `PatientAggregationService` 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 Patient **Update**
+
+- **`updatePatientInfoInCalendarEvents(patientId: string, patientInfo: any): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `patientId`.
+  - Updates the embedded `patientInfo` object in these calendar events with the provided `patientInfo`.
+
+### Methods Triggered by Patient **Deletion**
+
+- **`cancelUpcomingCalendarEventsForPatient(patientId: string): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `patientId`.
+  - Sets the `status` of these events to `CANCELED` and adds a `cancelReason` ("Patient deleted").

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

@@ -0,0 +1,42 @@
+# Practitioner Aggregation Service (Admin)
+
+This service centralizes the logic for updating aggregated data in various Firestore collections _when a practitioner is created, updated, or deleted_. It is designed primarily for use by Cloud Functions triggered by changes in the `practitioners` collection.
+
+## `PractitionerAggregationService` 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 Practitioner **Creation**
+
+- **`addPractitionerToClinic(clinicId: string, doctorInfo: DoctorInfo): Promise<void>`**
+  - Adds the `practitionerId` (from `doctorInfo.id`) and the `doctorInfo` object to the `doctors` and `doctorsInfo` arrays respectively in the specified `Clinic` document.
+  - Typically called for each clinic the new practitioner is associated with.
+
+### Methods Triggered by Practitioner **Update**
+
+- **`updatePractitionerInfoInClinics(clinicIds: string[], doctorInfo: DoctorInfo): Promise<void>`**
+  - Updates the aggregated `doctorsInfo` array within multiple `Clinic` documents associated with the practitioner.
+  - Uses a batch write to first remove the old `DoctorInfo` (matching by `id`) and then add the updated `doctorInfo`.
+- **`updatePractitionerInfoInProcedures(procedureIds: string[], doctorInfo: DoctorInfo): Promise<void>`**
+  - Updates the embedded `doctorInfo` object within multiple `Procedure` documents associated with the updated practitioner.
+- **`updatePractitionerInfoInCalendarEvents(practitionerId: string, practitionerInfo: DoctorInfo): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `practitionerId`.
+  - Updates the embedded `practitionerInfo` object in these calendar events.
+
+### Methods Triggered by Practitioner **Deletion**
+
+- **`removePractitionerFromClinics(clinicIds: string[], practitionerId: string): Promise<void>`**
+  - Removes the `practitionerId` from the `doctors` array and the corresponding `DoctorInfo` object (matching by `id`) from the `doctorsInfo` array in multiple `Clinic` documents.
+- **`cancelUpcomingCalendarEventsForPractitioner(practitionerId: string): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `practitionerId`.
+  - Sets the `status` of these events to `CANCELED` and adds a `cancelReason` ("Practitioner deleted").
+- **`removePractitionerFromPatients(patientIds: string[], practitionerId: string): Promise<void>`**
+  - Removes the `practitionerId` from the `doctorIds` array in multiple `Patient` documents.
+- **`inactivateProceduresForPractitioner(procedureIds: string[]): Promise<void>`**
+  - Sets the `isActive` flag to `false` for multiple `Procedure` documents associated with the deleted practitioner.

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

@@ -0,0 +1,43 @@
+# Procedure Aggregation Service (Admin)
+
+This service centralizes the logic for updating aggregated data in various Firestore collections _when a procedure is created, updated, or deleted/inactivated_. It is designed primarily for use by Cloud Functions triggered by changes in the `procedures` collection.
+
+## `ProcedureAggregationService` 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 Procedure **Creation**
+
+- **`addProcedureToPractitioner(practitionerId: string, procedureSummary: ProcedureSummaryInfo): Promise<void>`**
+  - Adds the `procedureId` (from `procedureSummary.id`) and the `procedureSummary` object to the `procedureIds` and `proceduresInfo` arrays respectively in the specified `Practitioner` document.
+- **`addProcedureToClinic(clinicId: string, procedureSummary: ProcedureSummaryInfo): Promise<void>`**
+  - Adds the `procedureId` (from `procedureSummary.id`) and the `procedureSummary` object to the `procedures` and `proceduresInfo` arrays respectively in the specified `Clinic` document.
+
+### Methods Triggered by Procedure **Update**
+
+- **`updateProcedureInfoInPractitioner(practitionerId: string, procedureSummary: ProcedureSummaryInfo): Promise<void>`**
+  - Updates the `proceduresInfo` array within the specified `Practitioner` document.
+  - Uses a transaction to read the existing array, filter out the old summary (matching by `id`), add the updated `procedureSummary`, and write the modified array back. This prevents race conditions.
+- **`updateProcedureInfoInClinic(clinicId: string, procedureSummary: ProcedureSummaryInfo): Promise<void>`**
+  - Updates the `proceduresInfo` array within the specified `Clinic` document using the same transaction-based read-modify-write pattern as above.
+- **`updateProcedureInfoInCalendarEvents(procedureId: string, procedureInfo: any): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `procedureId`.
+  - Updates the embedded `procedureInfo` object in these calendar events with the provided `procedureInfo`.
+
+### Methods Triggered by Procedure **Deletion / Deactivation**
+
+- **`cancelUpcomingCalendarEventsForProcedure(procedureId: string): Promise<void>`**
+  - Uses a Collection Group query (`calendar` subcollection) to find all _upcoming_ calendar events associated with the `procedureId`.
+  - Sets the `status` of these events to `CANCELED` and adds a `cancelReason` ("Procedure deleted or inactivated").
+- **`removeProcedureFromPractitioner(practitionerId: string, procedureId: string): Promise<void>`**
+  - Removes the `procedureId` from the `procedureIds` array and the corresponding `ProcedureSummaryInfo` object (matching by `id`) from the `proceduresInfo` array in the specified `Practitioner` document.
+  - Uses a transaction-based read-modify-write pattern.
+- **`removeProcedureFromClinic(clinicId: string, procedureId: string): Promise<void>`**
+  - Removes the `procedureId` from the `procedures` array and the corresponding `ProcedureSummaryInfo` object (matching by `id`) from the `proceduresInfo` array in the specified `Clinic` document.
+  - Uses a transaction-based read-modify-write pattern.

package/src/admin/index.ts

@@ -8,7 +8,11 @@ import { UserRole } from "../types";
 // Import types needed by admin consumers (like Cloud Functions)
 import { Clinic, ClinicLocation } from "../types/clinic";
 import { ClinicInfo } from "../types/profile";
-import { Practitioner } from "../types/practitioner";
+import {
+  Practitioner,
+  PractitionerToken,
+  PractitionerTokenStatus,
+} from "../types/practitioner";
 import { DoctorInfo } from "../types/clinic";
 import { Procedure, ProcedureSummaryInfo } from "../types/procedure";
 import { PatientProfile } from "../types/patient";
@@ -19,6 +23,10 @@ import { PractitionerAggregationService } from "./aggregation/practitioner/pract
 import { ProcedureAggregationService } from "./aggregation/procedure/procedure.aggregation.service";
 import { PatientAggregationService } from "./aggregation/patient/patient.aggregation.service";
 
+// Import mailing services
+import { BaseMailingService } from "./mailing/base.mailing.service";
+import { PractitionerInviteMailingService } from "./mailing/practitionerInvite/practitionerInvite.mailing";
+
 // Re-export types
 export type {
   Notification,
@@ -32,7 +40,11 @@ export type {
 // Re-export types needed by cloud functions
 export type { Clinic, ClinicLocation } from "../types/clinic";
 export type { ClinicInfo } from "../types/profile";
-export type { Practitioner } from "../types/practitioner";
+export type {
+  Practitioner,
+  PractitionerToken,
+  PractitionerTokenStatus,
+} from "../types/practitioner";
 export type { DoctorInfo } from "../types/clinic";
 export type { Procedure, ProcedureSummaryInfo } from "../types/procedure";
 export type { PatientProfile as Patient } from "../types/patient";
@@ -54,6 +66,9 @@ export {
   PatientAggregationService,
 };
 
+// Export mailing services
+export { BaseMailingService, PractitionerInviteMailingService };
+
 /**
  * Main entry point for the Admin module.
  * This module contains services and utilities intended for administrative tasks,

package/src/admin/mailing/README.md

@@ -0,0 +1,95 @@
+# Mailing Services
+
+This module provides mailing services for sending automated emails from the application using Mailgun.
+
+## Setup
+
+### 1. Install Dependencies
+
+Make sure to install the required dependencies:
+
+```bash
+npm install mailgun-js firebase-admin firebase-functions
+```
+
+### 2. Configure Mailgun
+
+To use the mailing services, you need to configure Mailgun credentials in your Firebase project:
+
+```bash
+firebase functions:config:set mailgun.api_key="your-mailgun-api-key" mailgun.domain="your-mailgun-domain" mailgun.from="MedClinic <no-reply@your-domain.com>"
+```
+
+To enable test mode (emails won't actually be sent):
+
+```bash
+firebase functions:config:set mailgun.test_mode="true"
+```
+
+### 3. Deploy Cloud Functions
+
+Deploy the cloud functions to start handling email sending events:
+
+```bash
+firebase deploy --only functions
+```
+
+## Available Services
+
+### Practitioner Invitation Service
+
+Sends email invitations to practitioners when they are invited to join a clinic.
+
+#### How it works:
+
+1. When a new practitioner token is created in the Firestore database, the `onPractitionerTokenCreated` cloud function is triggered.
+2. The function uses the `PractitionerInviteMailingService` to send an invitation email to the practitioner.
+3. The email contains the token needed to claim their profile and instructions for registration.
+
+#### Example Usage in Code:
+
+```typescript
+import { PractitionerInviteMailingService } from "./admin/mailing";
+
+// Create a new instance of the service
+const mailingService = new PractitionerInviteMailingService();
+
+// Send an invitation email
+await mailingService.sendInvitationEmail({
+  token: {
+    id: "token-id",
+    token: "ABC123",
+    practitionerId: "practitioner-id",
+    email: "doctor@example.com",
+    clinicId: "clinic-id",
+    expiresAt: admin.firestore.Timestamp.fromDate(new Date()),
+  },
+  practitioner: {
+    firstName: "John",
+    lastName: "Doe",
+  },
+  clinic: {
+    name: "Example Clinic",
+    contactEmail: "admin@example.com",
+    contactName: "Clinic Admin",
+  },
+  options: {
+    registrationUrl: "https://your-app.com/register",
+    customSubject: "Join Our Clinic",
+  },
+});
+```
+
+## Adding New Mailing Services
+
+To add a new mailing service:
+
+1. Create a new directory in the `mailing` folder for your service
+2. Create a service class that extends `BaseMailingService`
+3. Create an HTML template in a `templates` subfolder
+4. Create a cloud function to trigger the email sending
+5. Export your new service in the index files
+
+## Logging
+
+All email sending attempts are logged to the `email_logs` collection in Firestore for tracking and debugging purposes.

package/src/admin/mailing/base.mailing.service.ts

@@ -0,0 +1,131 @@
+import * as mailgun from "mailgun-js";
+import * as admin from "firebase-admin";
+// Configuration is no longer read here
+// import {
+//   getMailgunConfig,
+//   createMailgunClient,
+//   MailgunConfig,
+// } from "./mailgun.config";
+
+/**
+ * Base mailing service class that provides common functionality for all mailing services
+ */
+export class BaseMailingService {
+  protected db: FirebaseFirestore.Firestore;
+  protected mailgunClient: mailgun.Mailgun;
+  // Removed config property as it's no longer managed here
+  // protected config: MailgunConfig;
+
+  /**
+   * Constructor for BaseMailingService
+   * @param firestore Firestore instance provided by the caller
+   * @param mailgunClient Mailgun client instance provided by the caller
+   */
+  constructor(
+    firestore: FirebaseFirestore.Firestore,
+    mailgunClient: mailgun.Mailgun // Mailgun client is now required
+    // mailgunConfig?: MailgunConfig // Removed config parameter
+  ) {
+    // Use provided instances
+    this.db = firestore;
+    this.mailgunClient = mailgunClient;
+    // Removed internal config reading and client creation
+    // this.config = mailgunConfig || getMailgunConfig();
+    // this.mailgunClient = createMailgunClient(this.config);
+  }
+
+  /**
+   * Sends an email using Mailgun
+   * @param data Email data to send, including the 'from' address
+   * @returns Promise with the sending result
+   */
+  protected async sendEmail(
+    data: mailgun.messages.SendData // Caller must provide 'from'
+  ): Promise<mailgun.messages.SendResponse> {
+    try {
+      // Ensure 'from' field is provided by the caller
+      if (!data.from) {
+        throw new Error(
+          "Email 'from' address must be provided in sendEmail data."
+        );
+      }
+      // Removed fallback to internal config.from
+      // const emailData = {
+      //   ...data,
+      //   from: data.from || this.config.from,
+      // };
+
+      // Send the email
+      return await new Promise<mailgun.messages.SendResponse>(
+        (resolve, reject) => {
+          this.mailgunClient.messages().send(data, (error, body) => {
+            if (error) {
+              console.error("[BaseMailingService] Error sending email:", error);
+              reject(error);
+            } else {
+              console.log(
+                "[BaseMailingService] Email sent successfully:",
+                body
+              );
+              resolve(body);
+            }
+          });
+        }
+      );
+    } catch (error) {
+      console.error("[BaseMailingService] Error in sendEmail:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Logs email sending attempt to Firestore for tracking
+   * @param emailData Email data that was sent
+   * @param success Whether the email was sent successfully
+   * @param error Error object if the email failed to send
+   */
+  protected async logEmailAttempt(
+    emailData: { to: string; subject: string; templateName?: string },
+    success: boolean,
+    error?: any
+  ): Promise<void> {
+    try {
+      const emailLogRef = this.db.collection("email_logs").doc();
+      await emailLogRef.set({
+        to: emailData.to,
+        subject: emailData.subject,
+        templateName: emailData.templateName,
+        success,
+        error: error ? JSON.stringify(error) : null,
+        sentAt: admin.firestore.FieldValue.serverTimestamp(),
+      });
+    } catch (logError) {
+      console.error(
+        "[BaseMailingService] Error logging email attempt:",
+        logError
+      );
+      // Don't throw here to prevent disrupting the main flow
+    }
+  }
+
+  /**
+   * Renders a simple HTML email template with variables
+   * @param template HTML template string
+   * @param variables Key-value pairs to replace in the template
+   * @returns Rendered HTML string
+   */
+  protected renderTemplate(
+    template: string,
+    variables: Record<string, string>
+  ): string {
+    let rendered = template;
+
+    // Replace template variables (format: {{variable_name}})
+    Object.entries(variables).forEach(([key, value]) => {
+      const regex = new RegExp(`{{\\s*${key}\\s*}}`, "g");
+      rendered = rendered.replace(regex, value);
+    });
+
+    return rendered;
+  }
+}

package/src/admin/mailing/index.ts

@@ -0,0 +1,2 @@
+export * from "./base.mailing.service";
+export * from "./practitionerInvite";

package/src/admin/mailing/practitionerInvite/index.ts

@@ -0,0 +1 @@
+export * from "./practitionerInvite.mailing";