@blackcode_sa/metaestetics-api 1.14.28 → 1.14.32

package/src/admin/mailing/README.md

@@ -46,6 +46,50 @@ Sends email invitations to practitioners when they are invited to join a clinic.
 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.
 
+### Patient Invitation Service
+
+Sends email invitations to patients when a clinic admin creates their profile and generates an invitation token.
+
+#### How it works:
+
+1. When a new patient invitation token is created in the Firestore database (`patients/{patientId}/inviteTokens/{tokenId}`), the `onPatientTokenCreated` cloud function is triggered.
+2. The function uses the `PatientInviteMailingService` to send an invitation email to the patient.
+3. The email contains the token needed to claim their profile and instructions for registering in the patient app.
+
+#### Example Usage in Code:
+
+```typescript
+import { PatientInviteMailingService } from "./admin/mailing";
+
+// Create a new instance of the service
+const mailingService = new PatientInviteMailingService(firestoreClient, mailgunClient);
+
+// Send an invitation email
+await mailingService.sendInvitationEmail({
+  token: {
+    id: "token-id",
+    token: "ABC123",
+    patientId: "patient-id",
+    email: "patient@example.com",
+    clinicId: "clinic-id",
+    expiresAt: admin.firestore.Timestamp.fromDate(new Date()),
+  },
+  patient: {
+    firstName: "Jane",
+    lastName: "Doe",
+  },
+  clinic: {
+    name: "Example Clinic",
+    contactEmail: "admin@example.com",
+    contactName: "Clinic Admin",
+  },
+  options: {
+    registrationUrl: "https://your-app.com/patient/register",
+    customSubject: "Claim Your Patient Profile",
+  },
+});
+```
+
 #### Example Usage in Code:
 
 ```typescript

package/src/admin/mailing/index.ts

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

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

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

package/src/admin/mailing/patientInvite/patientInvite.mailing.ts

@@ -0,0 +1,415 @@
+import * as admin from "firebase-admin";
+import { BaseMailingService } from "../base.mailing.service";
+import { patientInvitationTemplate } from "./templates/invitation.template";
+import { Logger } from "../../logger";
+import {
+  PatientProfile,
+  PatientSensitiveInfo,
+  PATIENTS_COLLECTION,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+} from "../../../types/patient";
+import {
+  PatientToken,
+  PatientTokenStatus,
+  INVITE_TOKENS_COLLECTION,
+} from "../../../types/patient/token.types";
+import { Clinic, CLINICS_COLLECTION } from "../../../types/clinic";
+
+/**
+ * Minimal interface for the mailgun.js client if not importing full types
+ */
+interface NewMailgunMessagesAPI {
+  create(domain: string, data: any): Promise<any>;
+}
+interface NewMailgunClient {
+  messages: NewMailgunMessagesAPI;
+}
+
+/**
+ * Interface for the data required to send a patient invitation email
+ */
+export interface PatientInviteEmailData {
+  /** The token object from the patient service */
+  token: {
+    id: string;
+    token: string;
+    patientId: string;
+    email: string;
+    clinicId: string;
+    expiresAt: admin.firestore.Timestamp;
+  };
+
+  /** Patient basic info */
+  patient: {
+    firstName: string;
+    lastName: string;
+  };
+
+  /** Clinic info */
+  clinic: {
+    name: string;
+    contactEmail: string;
+    contactName?: string;
+  };
+
+  /** Config options */
+  options?: {
+    registrationUrl?: string;
+    customSubject?: string;
+    fromAddress?: string;
+    mailgunDomain?: string;
+  };
+}
+
+/**
+ * Service for sending patient invitation emails
+ * Follows the same pattern as PractitionerInviteMailingService
+ */
+export class PatientInviteMailingService extends BaseMailingService {
+  private readonly DEFAULT_REGISTRATION_URL =
+    "https://metaesthetics.net/patient/register";
+  private readonly DEFAULT_SUBJECT =
+    "Claim Your Patient Profile - MetaEstetics";
+  private readonly DEFAULT_MAILGUN_DOMAIN = "mg.metaesthetics.net";
+
+  /**
+   * Constructor for PatientInviteMailingService
+   * @param firestore - Firestore instance provided by the caller
+   * @param mailgunClient - Mailgun client instance (mailgun.js v10+) provided by the caller
+   */
+  constructor(
+    firestore: FirebaseFirestore.Firestore,
+    mailgunClient: NewMailgunClient
+  ) {
+    super(firestore, mailgunClient);
+  }
+
+  /**
+   * Sends a patient invitation email
+   * @param data - The patient invitation data
+   * @returns Promise resolved when email is sent
+   */
+  async sendInvitationEmail(data: PatientInviteEmailData): Promise<any> {
+    try {
+      Logger.info(
+        "[PatientInviteMailingService] Sending invitation email to",
+        data.token.email
+      );
+
+      // Format expiration date
+      const expirationDate = data.token.expiresAt
+        .toDate()
+        .toLocaleDateString("en-US", {
+          weekday: "long",
+          year: "numeric",
+          month: "long",
+          day: "numeric",
+        });
+
+      // Registration URL
+      const registrationUrl =
+        data.options?.registrationUrl || this.DEFAULT_REGISTRATION_URL;
+
+      // Contact information
+      const contactName = data.clinic.contactName || "Clinic Administrator";
+      const contactEmail = data.clinic.contactEmail;
+
+      // Subject line
+      const subject = data.options?.customSubject || this.DEFAULT_SUBJECT;
+
+      // Determine 'from' address
+      const fromAddress =
+        data.options?.fromAddress ||
+        `MetaEstetics <no-reply@${
+          data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN
+        }>`;
+
+      // Current year for copyright
+      const currentYear = new Date().getFullYear().toString();
+
+      // Patient full name
+      const patientName = `${data.patient.firstName} ${data.patient.lastName}`;
+
+      // Prepare template variables
+      const templateVariables = {
+        clinicName: data.clinic.name,
+        patientName,
+        inviteToken: data.token.token,
+        expirationDate,
+        registrationUrl,
+        contactName,
+        contactEmail,
+        currentYear,
+      };
+
+      // Debug log for template variables (excluding token for security)
+      Logger.info("[PatientInviteMailingService] Template variables:", {
+        clinicName: templateVariables.clinicName,
+        patientName: templateVariables.patientName,
+        expirationDate: templateVariables.expirationDate,
+        registrationUrl: templateVariables.registrationUrl,
+        contactName: templateVariables.contactName,
+        contactEmail: templateVariables.contactEmail,
+        hasInviteToken: !!templateVariables.inviteToken,
+      });
+
+      // Render HTML email
+      const html = this.renderTemplate(
+        patientInvitationTemplate,
+        templateVariables
+      );
+
+      // Data for the sendEmail method
+      const mailgunSendData = {
+        to: data.token.email,
+        from: fromAddress,
+        subject,
+        html,
+      };
+
+      // Determine the domain to use for sending
+      const domainToSendFrom =
+        data.options?.mailgunDomain || this.DEFAULT_MAILGUN_DOMAIN;
+
+      Logger.info("[PatientInviteMailingService] Sending email with data:", {
+        domain: domainToSendFrom,
+        to: mailgunSendData.to,
+        from: mailgunSendData.from,
+        subject: mailgunSendData.subject,
+        hasHtml: !!mailgunSendData.html,
+      });
+
+      // Call the sendEmail method from BaseMailingService
+      const result = await this.sendEmail(domainToSendFrom, mailgunSendData);
+
+      // Log success
+      await this.logEmailAttempt(
+        {
+          to: data.token.email,
+          subject,
+          templateName: "patient_invitation",
+        },
+        true
+      );
+
+      return result;
+    } catch (error: any) {
+      Logger.error(
+        "[PatientInviteMailingService] Error sending invitation email:",
+        {
+          errorMessage: error.message,
+          errorDetails: error.details,
+          errorStatus: error.status,
+          stack: error.stack,
+        }
+      );
+
+      // Log failure
+      await this.logEmailAttempt(
+        {
+          to: data.token.email,
+          subject: data.options?.customSubject || this.DEFAULT_SUBJECT,
+          templateName: "patient_invitation",
+        },
+        false,
+        error
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * Handles the patient token creation event from Cloud Functions.
+   * Fetches necessary data and sends the invitation email.
+   * @param tokenData - The fully typed token object including its id
+   * @param mailgunConfig - Mailgun configuration (from, domain, optional registrationUrl)
+   * @returns Promise resolved when the email is sent
+   */
+  async handleTokenCreationEvent(
+    tokenData: PatientToken,
+    mailgunConfig: {
+      fromAddress: string;
+      domain: string;
+      registrationUrl?: string;
+    }
+  ): Promise<void> {
+    try {
+      Logger.info(
+        "[PatientInviteMailingService] Handling token creation event for token:",
+        tokenData.id
+      );
+
+      // Validate token data
+      if (!tokenData || !tokenData.id || !tokenData.token || !tokenData.email) {
+        throw new Error(
+          `Invalid token data: Missing required properties. Token ID: ${tokenData?.id}`
+        );
+      }
+
+      if (!tokenData.patientId) {
+        throw new Error(
+          `Token ${tokenData.id} is missing patientId reference`
+        );
+      }
+
+      if (!tokenData.clinicId) {
+        throw new Error(`Token ${tokenData.id} is missing clinicId reference`);
+      }
+
+      if (!tokenData.expiresAt) {
+        throw new Error(`Token ${tokenData.id} is missing expiration date`);
+      }
+
+      // Validate token status (handle both enum and string values)
+      if (
+        tokenData.status !== PatientTokenStatus.ACTIVE &&
+        String(tokenData.status).toLowerCase() !== "active"
+      ) {
+        Logger.warn(
+          "[PatientInviteMailingService] Token is not active, skipping email.",
+          { tokenId: tokenData.id, status: tokenData.status }
+        );
+        return;
+      }
+
+      Logger.info(
+        `[PatientInviteMailingService] Token status validation:`,
+        {
+          tokenId: tokenData.id,
+          status: tokenData.status,
+          statusType: typeof tokenData.status,
+        }
+      );
+
+      // Get patient profile data
+      Logger.info(
+        `[PatientInviteMailingService] Fetching patient data: ${tokenData.patientId}`
+      );
+      const patientRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(tokenData.patientId);
+      const patientDoc = await patientRef.get();
+
+      if (!patientDoc.exists) {
+        throw new Error(`Patient ${tokenData.patientId} not found`);
+      }
+
+      const patientData = patientDoc.data() as PatientProfile;
+      if (!patientData) {
+        throw new Error(
+          `Patient ${tokenData.patientId} has invalid data structure`
+        );
+      }
+
+      // Get patient sensitive info for name
+      const sensitiveInfoRef = patientRef
+        .collection(PATIENT_SENSITIVE_INFO_COLLECTION)
+        .doc(tokenData.patientId);
+      const sensitiveInfoDoc = await sensitiveInfoRef.get();
+
+      let firstName = "Patient";
+      let lastName = "";
+
+      if (sensitiveInfoDoc.exists) {
+        const sensitiveInfo = sensitiveInfoDoc.data() as PatientSensitiveInfo;
+        firstName = sensitiveInfo?.firstName || "Patient";
+        lastName = sensitiveInfo?.lastName || "";
+      } else {
+        // Fall back to displayName if no sensitive info
+        Logger.warn(
+          `[PatientInviteMailingService] No sensitive info found for patient ${tokenData.patientId}, using displayName`
+        );
+        const displayNameParts = (patientData.displayName || "Patient").split(" ");
+        firstName = displayNameParts[0] || "Patient";
+        lastName = displayNameParts.slice(1).join(" ") || "";
+      }
+
+      Logger.info(
+        `[PatientInviteMailingService] Patient found: ${firstName} ${lastName}`
+      );
+
+      // Get clinic data
+      Logger.info(
+        `[PatientInviteMailingService] Fetching clinic data: ${tokenData.clinicId}`
+      );
+      const clinicRef = this.db
+        .collection(CLINICS_COLLECTION)
+        .doc(tokenData.clinicId);
+      const clinicDoc = await clinicRef.get();
+
+      if (!clinicDoc.exists) {
+        throw new Error(`Clinic ${tokenData.clinicId} not found`);
+      }
+
+      const clinicData = clinicDoc.data() as Clinic;
+      if (!clinicData || !clinicData.contactInfo) {
+        throw new Error(
+          `Clinic ${tokenData.clinicId} has invalid data structure`
+        );
+      }
+
+      Logger.info(
+        `[PatientInviteMailingService] Clinic found: ${clinicData.name}`
+      );
+
+      // Validate fromAddress
+      if (!mailgunConfig.fromAddress) {
+        Logger.warn(
+          "[PatientInviteMailingService] No fromAddress provided, using default"
+        );
+        mailgunConfig.fromAddress = `MetaEstetics <no-reply@${this.DEFAULT_MAILGUN_DOMAIN}>`;
+      }
+
+      // Prepare email data
+      const emailData: PatientInviteEmailData = {
+        token: {
+          id: tokenData.id,
+          token: tokenData.token,
+          patientId: tokenData.patientId,
+          email: tokenData.email,
+          clinicId: tokenData.clinicId,
+          expiresAt: tokenData.expiresAt as unknown as admin.firestore.Timestamp,
+        },
+        patient: {
+          firstName,
+          lastName,
+        },
+        clinic: {
+          name: clinicData.name || "Medical Clinic",
+          contactEmail: clinicData.contactInfo.email || "contact@clinic.com",
+          contactName: "Clinic Admin",
+        },
+        options: {
+          fromAddress: mailgunConfig.fromAddress,
+          mailgunDomain: mailgunConfig.domain,
+          registrationUrl: mailgunConfig.registrationUrl,
+        },
+      };
+
+      Logger.info(
+        "[PatientInviteMailingService] Email data prepared, sending invitation"
+      );
+
+      // Send the invitation email
+      await this.sendInvitationEmail(emailData);
+
+      Logger.info(
+        "[PatientInviteMailingService] Invitation email sent successfully"
+      );
+    } catch (error: any) {
+      Logger.error(
+        "[PatientInviteMailingService] Error handling token creation event:",
+        {
+          errorMessage: error.message,
+          errorDetails: error.details,
+          errorStatus: error.status,
+          stack: error.stack,
+          tokenId: tokenData?.id,
+        }
+      );
+      throw error;
+    }
+  }
+}
+

package/src/admin/mailing/patientInvite/templates/invitation.template.ts

@@ -0,0 +1,120 @@
+/**
+ * HTML email template for patient invitation to claim their profile
+ */
+export const patientInvitationTemplate = `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Claim Your Patient Profile at {{clinicName}}</title>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      line-height: 1.6;
+      color: #333;
+      margin: 0;
+      padding: 0;
+    }
+    .container {
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    .header {
+      background-color: #2C8E99;
+      padding: 20px;
+      text-align: center;
+      color: white;
+    }
+    .content {
+      padding: 20px;
+      background-color: #f9f9f9;
+    }
+    .footer {
+      padding: 20px;
+      text-align: center;
+      font-size: 12px;
+      color: #888;
+    }
+    .button {
+      display: inline-block;
+      background-color: #2C8E99;
+      color: white;
+      text-decoration: none;
+      padding: 12px 24px;
+      border-radius: 4px;
+      margin: 20px 0;
+      font-weight: bold;
+    }
+    .token {
+      font-size: 28px;
+      font-weight: bold;
+      color: #2C8E99;
+      padding: 15px 25px;
+      background-color: #e0f4f6;
+      border-radius: 8px;
+      display: inline-block;
+      letter-spacing: 4px;
+      margin: 15px 0;
+      font-family: monospace;
+    }
+    .info-box {
+      background-color: #fff;
+      border-left: 4px solid #2C8E99;
+      padding: 15px;
+      margin: 20px 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <h1>Welcome to MetaEstetics</h1>
+    </div>
+    <div class="content">
+      <p>Hello {{patientName}},</p>
+      
+      <p>A patient profile has been created for you at <strong>{{clinicName}}</strong>. You can now claim this profile to access your personal health dashboard and appointment history.</p>
+      
+      <div class="info-box">
+        <p><strong>What you'll get access to:</strong></p>
+        <ul>
+          <li>Your complete treatment history</li>
+          <li>Upcoming appointment details</li>
+          <li>Pre and post-treatment instructions</li>
+          <li>Direct messaging with your clinic</li>
+        </ul>
+      </div>
+      
+      <p>To claim your profile, use this registration token:</p>
+      
+      <div style="text-align: center;">
+        <span class="token">{{inviteToken}}</span>
+      </div>
+      
+      <p><strong>Important:</strong> This token will expire on <strong>{{expirationDate}}</strong>.</p>
+      
+      <p>To create your account:</p>
+      <ol>
+        <li>Download the MetaEstetics Patient app or visit {{registrationUrl}}</li>
+        <li>Create an account using your email address</li>
+        <li>When prompted, enter the token shown above</li>
+        <li>Your profile will be automatically linked to your new account</li>
+      </ol>
+      
+      <div style="text-align: center;">
+        <a href="{{registrationUrl}}" class="button">Create Your Account</a>
+      </div>
+      
+      <p>If you have any questions or didn't expect this email, please contact {{contactName}} at {{contactEmail}}.</p>
+    </div>
+    <div class="footer">
+      <p>This is an automated message from {{clinicName}}. Please do not reply to this email.</p>
+      <p>&copy; {{currentYear}} MetaEstetics. All rights reserved.</p>
+    </div>
+  </div>
+</body>
+</html>
+`;
+

package/src/services/calendar/utils/calendar-event.utils.ts

@@ -622,7 +622,15 @@ export async function searchCalendarEventsUtil(
   }
   if (filters.dateRange) {
     // Firestore requires range filters on the same field
-    constraints.push(where("eventTime.start", ">=", filters.dateRange.start));
+    // We query for events that start within or before the date range
+    // Then post-filter to ensure they overlap (eventTime.end > dateRange.start)
+    // To catch events that start before but overlap, we extend the query start backwards
+    const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days for long blocking events
+    const extendedStart = Timestamp.fromMillis(
+      filters.dateRange.start.toMillis() - MAX_EVENT_DURATION_MS
+    );
+    
+    constraints.push(where("eventTime.start", ">=", extendedStart));
     constraints.push(where("eventTime.start", "<=", filters.dateRange.end));
     // Note: You might need to order by eventTime.start for range filters to work efficiently
     // constraints.push(orderBy("eventTime.start"));
@@ -633,10 +641,32 @@ export async function searchCalendarEventsUtil(
     const finalQuery = query(collectionRef, ...constraints);
     const querySnapshot = await getDocs(finalQuery);
 
-    const events = querySnapshot.docs.map(
+    let events = querySnapshot.docs.map(
       (doc) => ({ id: doc.id, ...doc.data() } as CalendarEvent)
     );
 
+    // Post-filter to ensure events actually overlap with the date range (if provided)
+    // An event overlaps if: eventTime.start < dateRange.end AND eventTime.end > dateRange.start
+    if (filters.dateRange) {
+      events = events.filter((event) => {
+        const overlaps =
+          event.eventTime.end.toMillis() > filters.dateRange!.start.toMillis();
+        if (!overlaps) {
+          console.debug(
+            `[searchCalendarEventsUtil] Filtered out non-overlapping event:`,
+            {
+              eventId: event.id,
+              eventStart: event.eventTime.start.toDate().toISOString(),
+              eventEnd: event.eventTime.end.toDate().toISOString(),
+              queryStart: filters.dateRange!.start.toDate().toISOString(),
+              queryEnd: filters.dateRange!.end.toDate().toISOString(),
+            }
+          );
+        }
+        return overlaps;
+      });
+    }
+
     return events;
   } catch (error) {
     console.error("Error searching calendar events:", error);