@blackcode_sa/metaestetics-api 1.6.4 → 1.6.6

package/src/admin/calendar/calendar.admin.service.ts

@@ -0,0 +1,183 @@
+import * as admin from "firebase-admin";
+import { Appointment, APPOINTMENTS_COLLECTION } from "../../types/appointment";
+import {
+  CalendarEventStatus,
+  CalendarEventTime,
+  CALENDAR_COLLECTION,
+} from "../../types/calendar";
+import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
+import { Logger } from "../logger";
+import { PRACTITIONERS_COLLECTION } from "../../types/practitioner";
+import { PATIENTS_COLLECTION } from "../../types/patient";
+import { CLINICS_COLLECTION } from "../../types/clinic";
+
+/**
+ * @class CalendarAdminService
+ * @description Handles administrative tasks for calendar events linked to appointments,
+ * such as status updates, time changes, or deletions, subsequent to their initial creation.
+ */
+export class CalendarAdminService {
+  private db: admin.firestore.Firestore;
+
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    Logger.info("[CalendarAdminService] Initialized.");
+  }
+
+  /**
+   * Updates the status of all three calendar events (practitioner, patient, clinic)
+   * associated with a given appointment.
+   *
+   * @param appointment - The appointment object containing references to its calendar events.
+   * @param newStatus - The new CalendarEventStatus to set.
+   * @returns {Promise<void>} A promise that resolves when all updates are attempted.
+   */
+  async updateAppointmentCalendarEventsStatus(
+    appointment: Appointment,
+    newStatus: CalendarEventStatus
+  ): Promise<void> {
+    Logger.info(
+      `[CalendarAdminService] Updating calendar event statuses for appointment ${appointment.id} to ${newStatus}`
+    );
+    const batch = this.db.batch();
+    const serverTimestamp = admin.firestore.FieldValue.serverTimestamp();
+
+    // Note: The Appointment type in booking.admin.ts has `calendarEventId` (practitioner's event)
+    // but not direct IDs for patient and clinic calendar events.
+    // We need a robust way to find these if they aren't directly on the appointment object.
+    // For now, assuming we can query them or they are added to the Appointment type.
+
+    // Let's assume the main appointment.calendarEventId is the practitioner's calendar event.
+    // The other calendar event IDs might need to be fetched or stored on the Appointment object.
+    // For this placeholder, we'll demonstrate updating one and note the others.
+
+    // TODO: Confirm how patient and clinic calendar event IDs are retrieved.
+    // Assuming they are named predictably or stored in appointment.additionalCalendarEventIds (example)
+
+    const practitionerCalendarEventPath = `${PRACTITIONERS_COLLECTION}/${appointment.practitionerId}/${CALENDAR_COLLECTION}/${appointment.calendarEventId}`;
+    // Example paths, these need to be accurate based on your data model:
+    // const patientCalendarEventPath = `${PATIENTS_COLLECTION}/${appointment.patientId}/${CALENDAR_COLLECTION}/${appointment.patientCalendarEventId}`;
+    // const clinicCalendarEventPath = `${CLINICS_COLLECTION}/${appointment.clinicBranchId}/${CALENDAR_COLLECTION}/${appointment.clinicCalendarEventId}`;
+
+    if (appointment.calendarEventId) {
+      // Practitioner event
+      const practitionerEventRef = this.db.doc(practitionerCalendarEventPath);
+      batch.update(practitionerEventRef, {
+        status: newStatus,
+        updatedAt: serverTimestamp,
+      });
+    }
+    // Add similar updates for patient and clinic calendar events once their refs are confirmed
+    // if (appointment.patientCalendarEventId) { ... }
+    // if (appointment.clinicCalendarEventId) { ... }
+
+    try {
+      await batch.commit();
+      Logger.info(
+        `[CalendarAdminService] Successfully updated calendar event statuses for appointment ${appointment.id}.`
+      );
+    } catch (error) {
+      Logger.error(
+        `[CalendarAdminService] Error updating calendar event statuses for appointment ${appointment.id}:`,
+        error
+      );
+      // Decide on error handling: re-throw, or log and continue?
+    }
+  }
+
+  /**
+   * Updates the eventTime (start and end) of all three calendar events
+   * associated with a given appointment.
+   *
+   * @param appointment - The appointment object.
+   * @param newEventTime - The new CalendarEventTime object (using FirebaseClientTimestamp).
+   * @returns {Promise<void>} A promise that resolves when all updates are attempted.
+   */
+  async updateAppointmentCalendarEventsTime(
+    appointment: Appointment,
+    newEventTime: CalendarEventTime // Expecting { start: FirebaseClientTimestamp, end: FirebaseClientTimestamp }
+  ): Promise<void> {
+    Logger.info(
+      `[CalendarAdminService] Updating calendar event times for appointment ${appointment.id}`
+    );
+    const batch = this.db.batch();
+    const serverTimestamp = admin.firestore.FieldValue.serverTimestamp();
+
+    // Convert FirebaseClientTimestamp to a plain object for Firestore admin SDK if needed,
+    // or ensure the CalendarEventTime type is directly compatible.
+    // Firestore admin SDK usually handles { seconds: X, nanoseconds: Y } objects correctly.
+    const firestoreCompatibleEventTime = {
+      start: {
+        seconds: newEventTime.start.seconds,
+        nanoseconds: newEventTime.start.nanoseconds,
+      },
+      end: {
+        seconds: newEventTime.end.seconds,
+        nanoseconds: newEventTime.end.nanoseconds,
+      },
+    };
+
+    // TODO: Confirm paths as in updateAppointmentCalendarEventsStatus
+    if (appointment.calendarEventId) {
+      // Practitioner event
+      const practitionerEventRef = this.db.doc(
+        `${PRACTITIONERS_COLLECTION}/${appointment.practitionerId}/${CALENDAR_COLLECTION}/${appointment.calendarEventId}`
+      );
+      batch.update(practitionerEventRef, {
+        eventTime: firestoreCompatibleEventTime,
+        updatedAt: serverTimestamp,
+      });
+    }
+    // Add similar updates for patient and clinic calendar events
+
+    try {
+      await batch.commit();
+      Logger.info(
+        `[CalendarAdminService] Successfully updated calendar event times for appointment ${appointment.id}.`
+      );
+    } catch (error) {
+      Logger.error(
+        `[CalendarAdminService] Error updating calendar event times for appointment ${appointment.id}:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Deletes all three calendar events associated with a given appointment.
+   * Note: This is a hard delete. Consider marking as CANCELLED instead if soft delete is preferred.
+   *
+   * @param appointment - The appointment object.
+   * @returns {Promise<void>} A promise that resolves when all deletions are attempted.
+   */
+  async deleteAppointmentCalendarEvents(
+    appointment: Appointment
+  ): Promise<void> {
+    Logger.info(
+      `[CalendarAdminService] Deleting calendar events for appointment ${appointment.id}`
+    );
+    const batch = this.db.batch();
+
+    // TODO: Confirm paths as in updateAppointmentCalendarEventsStatus
+    if (appointment.calendarEventId) {
+      // Practitioner event
+      const practitionerEventRef = this.db.doc(
+        `${PRACTITIONERS_COLLECTION}/${appointment.practitionerId}/${CALENDAR_COLLECTION}/${appointment.calendarEventId}`
+      );
+      batch.delete(practitionerEventRef);
+    }
+    // Add similar deletes for patient and clinic calendar events
+
+    try {
+      await batch.commit();
+      Logger.info(
+        `[CalendarAdminService] Successfully deleted calendar events for appointment ${appointment.id}.`
+      );
+    } catch (error) {
+      Logger.error(
+        `[CalendarAdminService] Error deleting calendar events for appointment ${appointment.id}:`,
+        error
+      );
+    }
+  }
+}

package/src/admin/documentation-templates/document-manager.admin.ts

@@ -0,0 +1,131 @@
+import * as admin from "firebase-admin";
+import {
+  DocumentTemplate,
+  FilledDocument,
+  FilledDocumentStatus,
+  USER_FORMS_SUBCOLLECTION,
+  DOCTOR_FORMS_SUBCOLLECTION,
+} from "../../types/documentation-templates";
+import {
+  APPOINTMENTS_COLLECTION,
+  LinkedFormInfo,
+} from "../../types/appointment";
+
+export interface InitializeAppointmentFormsResult {
+  initializedFormsInfo: LinkedFormInfo[];
+  pendingUserFormsIds: string[];
+  allLinkedTemplateIds: string[];
+}
+
+export class DocumentManagerAdminService {
+  private db: admin.firestore.Firestore;
+
+  constructor(firestore: admin.firestore.Firestore) {
+    this.db = firestore;
+  }
+
+  /**
+   * Adds operations to a Firestore batch to initialize all linked forms for a new appointment
+   * and returns an array of LinkedFormInfo objects, pendingUserFormsIds, and allLinkedTemplateIds.
+   *
+   * @param dbBatch - The Firestore batch to add operations to.
+   * @param appointmentId - The ID of the newly created appointment.
+   * @param procedureIdForForms - The ID of the procedure associated with this appointment.
+   * @param procedureTemplates - Array of document templates linked to the procedure.
+   * @param patientId - ID of the patient.
+   * @param practitionerId - ID of the practitioner associated with the procedure.
+   * @param clinicId - ID of the clinic where the procedure is performed.
+   * @param nowMillis - Current timestamp in milliseconds for createdAt/updatedAt.
+   * @returns An object containing initializedFormsInfo, pendingUserFormsIds, and allLinkedTemplateIds.
+   */
+  batchInitializeAppointmentForms(
+    dbBatch: admin.firestore.WriteBatch,
+    appointmentId: string,
+    procedureIdForForms: string,
+    procedureTemplates: DocumentTemplate[],
+    patientId: string,
+    practitionerId: string,
+    clinicId: string,
+    nowMillis: number
+  ): InitializeAppointmentFormsResult {
+    const initializedFormsInfo: LinkedFormInfo[] = [];
+    const pendingUserFormsIds: string[] = [];
+    const allLinkedTemplateIds: string[] = [];
+
+    if (!procedureTemplates || procedureTemplates.length === 0) {
+      console.log(
+        `[DocManagerAdmin] No document templates to initialize for appointment ${appointmentId}.`
+      );
+      return {
+        initializedFormsInfo,
+        pendingUserFormsIds,
+        allLinkedTemplateIds,
+      };
+    }
+
+    for (const template of procedureTemplates) {
+      const isUserForm = template.isUserForm || false;
+
+      const formSubcollectionPath = isUserForm
+        ? USER_FORMS_SUBCOLLECTION
+        : DOCTOR_FORMS_SUBCOLLECTION;
+
+      const filledDocumentId = this.db
+        .collection(APPOINTMENTS_COLLECTION)
+        .doc(appointmentId)
+        .collection(formSubcollectionPath)
+        .doc().id;
+
+      if (isUserForm && (template.isRequired || false)) {
+        pendingUserFormsIds.push(filledDocumentId);
+      }
+
+      allLinkedTemplateIds.push(filledDocumentId);
+      // Always initialize with PENDING status regardless of whether the form is required
+      // PENDING is the starting state, DRAFT is when a form is saved but not submitted
+      const initialStatus = FilledDocumentStatus.PENDING;
+
+      const filledDocumentData: FilledDocument = {
+        id: filledDocumentId,
+        templateId: template.id,
+        templateVersion: template.version,
+        isUserForm: isUserForm,
+        isRequired: template.isRequired || false,
+        appointmentId: appointmentId,
+        procedureId: procedureIdForForms,
+        patientId: patientId,
+        practitionerId: practitionerId,
+        clinicId: clinicId,
+        createdAt: nowMillis,
+        updatedAt: nowMillis,
+        values: {},
+        status: initialStatus,
+      };
+
+      const docRef = this.db
+        .collection(APPOINTMENTS_COLLECTION)
+        .doc(appointmentId)
+        .collection(formSubcollectionPath)
+        .doc(filledDocumentId);
+
+      dbBatch.set(docRef, filledDocumentData);
+
+      const linkedForm: LinkedFormInfo = {
+        formId: filledDocumentData.id,
+        templateId: template.id,
+        templateVersion: template.version,
+        title: template.title,
+        isUserForm: filledDocumentData.isUserForm,
+        isRequired: filledDocumentData.isRequired,
+        status: filledDocumentData.status,
+        path: docRef.path,
+      };
+      initializedFormsInfo.push(linkedForm);
+
+      console.log(
+        `[DocManagerAdmin] Added FilledDocument ${filledDocumentId} (template: ${template.id}) and its LinkedFormInfo to batch for appointment ${appointmentId}.`
+      );
+    }
+    return { initializedFormsInfo, pendingUserFormsIds, allLinkedTemplateIds };
+  }
+}

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

@@ -0,0 +1,264 @@
+import * as admin from "firebase-admin";
+import { BaseMailingService, NewMailgunClient } from "../base.mailing.service";
+import { Logger } from "../../logger";
+import { Appointment } from "../../../types/appointment";
+import { PatientProfile } from "../../../types/patient";
+import { Practitioner } from "../../../types/practitioner";
+import { Clinic } from "../../../types/clinic";
+import { UserRole } from "../../../types";
+import {
+  PractitionerProfileInfo,
+  PatientProfileInfo,
+  ClinicInfo,
+} from "../../../types/profile";
+
+// Simple string literals for placeholders, to be replaced by file loading later
+const patientAppointmentConfirmedTemplate =
+  "<h1>Appointment Confirmed</h1><p>Dear {{patientName}},</p><p>Your appointment for {{procedureName}} on {{appointmentDate}} at {{appointmentTime}} with {{practitionerName}} at {{clinicName}} has been confirmed.</p><p>Thank you!</p>";
+const clinicAppointmentRequestedTemplate =
+  "<h1>New Appointment Request</h1><p>Hello {{clinicName}} Admin,</p><p>A new appointment for {{procedureName}} has been requested by {{patientName}} for {{appointmentDate}} at {{appointmentTime}} with {{practitionerName}}.</p><p>Please review and confirm in the admin panel.</p>";
+
+// --- Interface Definitions for Email Data ---
+
+export interface AppointmentEmailDataBase {
+  appointment: Appointment;
+  options?: {
+    customSubject?: string;
+    fromAddress?: string;
+    mailgunDomain?: string;
+  };
+}
+
+export interface AppointmentConfirmationEmailData
+  extends AppointmentEmailDataBase {
+  recipientProfile: PatientProfileInfo | PractitionerProfileInfo;
+  recipientRole: "patient" | "practitioner";
+}
+
+export interface AppointmentRequestedEmailData
+  extends AppointmentEmailDataBase {
+  clinicProfile: ClinicInfo;
+}
+
+export interface AppointmentCancellationEmailData
+  extends AppointmentEmailDataBase {
+  recipientProfile: PatientProfileInfo | PractitionerProfileInfo;
+  recipientRole: "patient" | "practitioner";
+  cancellationReason?: string;
+}
+
+export interface AppointmentRescheduledProposalEmailData
+  extends AppointmentEmailDataBase {
+  patientProfile: PatientProfileInfo;
+  previousStartTime: admin.firestore.Timestamp;
+  previousEndTime: admin.firestore.Timestamp;
+}
+
+export interface ReviewRequestEmailData extends AppointmentEmailDataBase {
+  patientProfile: PatientProfileInfo;
+  reviewLink: string;
+}
+
+export interface ReviewAddedEmailData extends AppointmentEmailDataBase {
+  recipientProfile: PractitionerProfileInfo | ClinicInfo;
+  recipientRole: "practitioner" | "clinic";
+  reviewerName: string;
+  reviewRating: number;
+  reviewComment?: string;
+}
+
+/**
+ * Service for sending appointment-related emails.
+ */
+export class AppointmentMailingService extends BaseMailingService {
+  private readonly DEFAULT_MAILGUN_DOMAIN = "mg.metaesthetics.net";
+
+  constructor(
+    firestore: admin.firestore.Firestore,
+    mailgunClient: NewMailgunClient
+  ) {
+    super(firestore, mailgunClient);
+    Logger.info("[AppointmentMailingService] Initialized.");
+  }
+
+  async sendAppointmentConfirmedEmail(
+    data: AppointmentConfirmationEmailData
+  ): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Preparing to send appointment confirmation email to ${data.recipientRole}: ${data.recipientProfile.id}`
+    );
+
+    const recipientEmail = data.recipientProfile.email;
+
+    if (!recipientEmail) {
+      Logger.error(
+        "[AppointmentMailingService] Recipient email not found for confirmation.",
+        { recipientId: data.recipientProfile.id, role: data.recipientRole }
+      );
+      throw new Error("Recipient email address is missing.");
+    }
+
+    const templateVariables = {
+      patientName: data.appointment.patientInfo.fullName,
+      procedureName: data.appointment.procedureInfo.name,
+      appointmentDate: data.appointment.appointmentStartTime
+        .toDate()
+        .toLocaleDateString(),
+      appointmentTime: data.appointment.appointmentStartTime
+        .toDate()
+        .toLocaleTimeString(),
+      practitionerName: data.appointment.practitionerInfo.name,
+      clinicName: data.appointment.clinicInfo.name,
+    };
+
+    const html = this.renderTemplate(
+      patientAppointmentConfirmedTemplate,
+      templateVariables
+    );
+    const subject =
+      data.options?.customSubject || "Your Appointment is Confirmed!";
+    const fromAddress =
+      data.options?.fromAddress ||
+      `MetaEstetics <no-reply@${
+        data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN
+      }>`;
+    const domainToSendFrom =
+      data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN;
+
+    const mailgunSendData = {
+      to: recipientEmail,
+      from: fromAddress,
+      subject,
+      html,
+    };
+
+    try {
+      const result = await this.sendEmail(domainToSendFrom, mailgunSendData);
+      await this.logEmailAttempt(
+        { to: recipientEmail, subject, templateName: "appointment_confirmed" },
+        true
+      );
+      return result;
+    } catch (error) {
+      await this.logEmailAttempt(
+        {
+          to: recipientEmail,
+          subject:
+            data.options?.customSubject || "Your Appointment is Confirmed!",
+          templateName: "appointment_confirmed",
+        },
+        false,
+        error
+      );
+      throw error;
+    }
+  }
+
+  async sendAppointmentRequestedEmailToClinic(
+    data: AppointmentRequestedEmailData
+  ): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Preparing to send appointment requested email to clinic: ${data.clinicProfile.id}`
+    );
+
+    const clinicEmail = data.clinicProfile.contactInfo?.email;
+    if (!clinicEmail) {
+      Logger.error(
+        "[AppointmentMailingService] Clinic contact email not found for request notification.",
+        { clinicId: data.clinicProfile.id }
+      );
+      throw new Error("Clinic contact email address is missing.");
+    }
+
+    const templateVariables = {
+      clinicName: data.clinicProfile.name,
+      patientName: data.appointment.patientInfo.fullName,
+      procedureName: data.appointment.procedureInfo.name,
+      appointmentDate: data.appointment.appointmentStartTime
+        .toDate()
+        .toLocaleDateString(),
+      appointmentTime: data.appointment.appointmentStartTime
+        .toDate()
+        .toLocaleTimeString(),
+      practitionerName: data.appointment.practitionerInfo.name,
+    };
+
+    const html = this.renderTemplate(
+      clinicAppointmentRequestedTemplate,
+      templateVariables
+    );
+    const subject =
+      data.options?.customSubject || "New Appointment Request Received";
+    const fromAddress =
+      data.options?.fromAddress ||
+      `MetaEstetics <no-reply@${
+        data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN
+      }>`;
+    const domainToSendFrom =
+      data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN;
+
+    const mailgunSendData = {
+      to: clinicEmail,
+      from: fromAddress,
+      subject,
+      html,
+    };
+
+    try {
+      const result = await this.sendEmail(domainToSendFrom, mailgunSendData);
+      await this.logEmailAttempt(
+        {
+          to: clinicEmail,
+          subject,
+          templateName: "appointment_requested_clinic",
+        },
+        true
+      );
+      return result;
+    } catch (error) {
+      await this.logEmailAttempt(
+        {
+          to: clinicEmail,
+          subject:
+            data.options?.customSubject || "New Appointment Request Received",
+          templateName: "appointment_requested_clinic",
+        },
+        false,
+        error
+      );
+      throw error;
+    }
+  }
+
+  async sendAppointmentCancelledEmail(
+    data: AppointmentCancellationEmailData
+  ): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Placeholder for sendAppointmentCancelledEmail for ${data.recipientRole}: ${data.recipientProfile.id}`
+    );
+    return Promise.resolve();
+  }
+
+  async sendAppointmentRescheduledProposalEmail(
+    data: AppointmentRescheduledProposalEmailData
+  ): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Placeholder for sendAppointmentRescheduledProposalEmail to patient: ${data.patientProfile.id}`
+    );
+    return Promise.resolve();
+  }
+
+  async sendReviewRequestEmail(data: ReviewRequestEmailData): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Placeholder for sendReviewRequestEmail to patient: ${data.patientProfile.id}`
+    );
+    return Promise.resolve();
+  }
+
+  async sendReviewAddedEmail(data: ReviewAddedEmailData): Promise<any> {
+    Logger.info(
+      `[AppointmentMailingService] Placeholder for sendReviewAddedEmail to ${data.recipientRole}: ${data.recipientProfile.id}`
+    );
+    return Promise.resolve();
+  }
+}

package/src/admin/mailing/appointment/templates/patient/appointment-confirmed.html

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Appointment Confirmed</title>
+    <style>
+      body {
+        font-family: Arial, sans-serif;
+        margin: 0;
+        padding: 20px;
+        color: #333;
+      }
+      .container {
+        background-color: #f9f9f9;
+        padding: 20px;
+        border-radius: 5px;
+      }
+      h1 {
+        color: #4caf50;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <h1>Appointment Confirmed!</h1>
+      <p>Dear {{patientName}},</p>
+      <p>
+        This is a placeholder email to confirm your appointment for
+        <strong>{{procedureName}}</strong>.
+      </p>
+      <p>Date: {{appointmentDate}}</p>
+      <p>Time: {{appointmentTime}}</p>
+      <p>With: {{practitionerName}}</p>
+      <p>At: {{clinicName}}</p>
+      <p>We look forward to seeing you!</p>
+      <p>Sincerely,<br />The {{clinicName}} Team</p>
+    </div>
+  </body>
+</html>

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

@@ -14,7 +14,7 @@ interface NewMailgunMessagesAPI {
   create(domain: string, data: any): Promise<any>;
 }
 
-interface NewMailgunClient {
+export interface NewMailgunClient {
   messages: NewMailgunMessagesAPI;
   // Add other methods/properties if your BaseMailingService uses them
 }

package/src/admin/mailing/index.ts

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