@blackcode_sa/metaestetics-api 1.5.29 → 1.5.31

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

@@ -0,0 +1,256 @@
+import * as admin from "firebase-admin";
+import * as mailgun from "mailgun-js";
+import { BaseMailingService } from "../base.mailing.service";
+import { practitionerInvitationTemplate } from "./templates/invitation.template";
+
+// Import specific types and collection constants
+import {
+  Practitioner,
+  PractitionerToken,
+  PRACTITIONERS_COLLECTION,
+} from "../../../types/practitioner";
+import { Clinic, CLINICS_COLLECTION } from "../../../types/clinic";
+
+/**
+ * Interface for the data required to send a practitioner invitation email
+ */
+export interface PractitionerInviteEmailData {
+  /** The token object from the practitioner service */
+  token: {
+    id: string;
+    token: string;
+    practitionerId: string;
+    email: string;
+    clinicId: string;
+    expiresAt: admin.firestore.Timestamp;
+  };
+
+  /** Practitioner basic info */
+  practitioner: {
+    firstName: string;
+    lastName: string;
+  };
+
+  /** Clinic info */
+  clinic: {
+    name: string;
+    contactEmail: string;
+    contactName?: string;
+  };
+
+  /** Config options */
+  options?: {
+    registrationUrl?: string;
+    customSubject?: string;
+    fromAddress?: string;
+  };
+}
+
+/**
+ * Service for sending practitioner invitation emails
+ */
+export class PractitionerInviteMailingService extends BaseMailingService {
+  private readonly DEFAULT_REGISTRATION_URL =
+    "https://app.medclinic.com/register";
+  private readonly DEFAULT_SUBJECT =
+    "You've Been Invited to Join as a Practitioner";
+  private readonly DEFAULT_FROM_ADDRESS =
+    "MedClinic <no-reply@your-domain.com>";
+
+  /**
+   * Constructor for PractitionerInviteMailingService
+   * @param firestore Firestore instance provided by the caller
+   * @param mailgunClient Mailgun client instance provided by the caller
+   */
+  constructor(
+    firestore: FirebaseFirestore.Firestore,
+    mailgunClient: mailgun.Mailgun
+  ) {
+    super(firestore, mailgunClient);
+  }
+
+  /**
+   * Sends a practitioner invitation email
+   * @param data The practitioner invitation data
+   * @returns Promise resolved when email is sent
+   */
+  async sendInvitationEmail(
+    data: PractitionerInviteEmailData
+  ): Promise<mailgun.messages.SendResponse> {
+    try {
+      console.log(
+        "[PractitionerInviteMailingService] 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 || this.DEFAULT_FROM_ADDRESS;
+
+      // Current year for copyright
+      const currentYear = new Date().getFullYear().toString();
+
+      // Practitioner full name
+      const practitionerName = `${data.practitioner.firstName} ${data.practitioner.lastName}`;
+
+      // Prepare template variables
+      const templateVariables = {
+        clinicName: data.clinic.name,
+        practitionerName,
+        inviteToken: data.token.token,
+        expirationDate,
+        registrationUrl,
+        contactName,
+        contactEmail,
+        currentYear,
+      };
+
+      // Render HTML email
+      const html = this.renderTemplate(
+        practitionerInvitationTemplate,
+        templateVariables
+      );
+
+      // Send email - ensure 'from' is included
+      const emailData: mailgun.messages.SendData = {
+        to: data.token.email,
+        from: fromAddress,
+        subject,
+        html,
+      };
+
+      const result = await this.sendEmail(emailData);
+
+      // Log success
+      await this.logEmailAttempt(
+        {
+          to: data.token.email,
+          subject,
+          templateName: "practitioner_invitation",
+        },
+        true
+      );
+
+      return result;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteMailingService] Error sending invitation email:",
+        error
+      );
+
+      // Log failure
+      await this.logEmailAttempt(
+        {
+          to: data.token.email,
+          subject: data.options?.customSubject || this.DEFAULT_SUBJECT,
+          templateName: "practitioner_invitation",
+        },
+        false,
+        error
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * Handles the practitioner token creation event from Cloud Functions
+   * Fetches necessary data using defined types and collection constants,
+   * and sends the invitation email.
+   * @param tokenData The fully typed token object including its id
+   * @param fromAddress The 'from' email address to use, obtained from config
+   * @returns Promise resolved when the email is sent
+   */
+  async handleTokenCreationEvent(
+    tokenData: PractitionerToken,
+    fromAddress: string
+  ): Promise<void> {
+    try {
+      console.log(
+        "[PractitionerInviteMailingService] Handling token creation event for token:",
+        tokenData.id
+      );
+
+      // Get practitioner data using constant and type
+      const practitionerRef = this.db
+        .collection(PRACTITIONERS_COLLECTION)
+        .doc(tokenData.practitionerId);
+      const practitionerDoc = await practitionerRef.get();
+
+      if (!practitionerDoc.exists) {
+        throw new Error(`Practitioner ${tokenData.practitionerId} not found`);
+      }
+
+      const practitionerData = practitionerDoc.data() as Practitioner;
+
+      // Get clinic data using constant and type
+      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;
+
+      // Prepare email data using typed data
+      const emailData: PractitionerInviteEmailData = {
+        token: {
+          id: tokenData.id,
+          token: tokenData.token,
+          practitionerId: tokenData.practitionerId,
+          email: tokenData.email,
+          clinicId: tokenData.clinicId,
+          expiresAt: tokenData.expiresAt,
+        },
+        practitioner: {
+          firstName: practitionerData.basicInfo.firstName || "",
+          lastName: practitionerData.basicInfo.lastName || "",
+        },
+        clinic: {
+          name: clinicData.name || "Medical Clinic",
+          contactEmail: clinicData.contactInfo.email || "contact@medclinic.com",
+        },
+        options: {
+          fromAddress: fromAddress,
+        },
+      };
+
+      // Send the invitation email
+      await this.sendInvitationEmail(emailData);
+
+      console.log(
+        "[PractitionerInviteMailingService] Invitation email sent successfully"
+      );
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteMailingService] Error handling token creation event:",
+        error
+      );
+      throw error;
+    }
+  }
+}

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

@@ -0,0 +1,101 @@
+/**
+ * HTML email template for practitioner invitation
+ */
+export const practitionerInvitationTemplate = `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Join {{clinicName}} as a Practitioner</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: #4A90E2;
+      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: #4A90E2;
+      color: white;
+      text-decoration: none;
+      padding: 12px 24px;
+      border-radius: 4px;
+      margin: 20px 0;
+      font-weight: bold;
+    }
+    .token {
+      font-size: 24px;
+      font-weight: bold;
+      color: #4A90E2;
+      padding: 10px;
+      background-color: #e9f0f9;
+      border-radius: 4px;
+      display: inline-block;
+      letter-spacing: 2px;
+      margin: 10px 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <h1>You've Been Invited</h1>
+    </div>
+    <div class="content">
+      <p>Hello {{practitionerName}},</p>
+      
+      <p>You have been invited to join <strong>{{clinicName}}</strong> as a healthcare practitioner.</p>
+      
+      <p>Your profile has been created and is ready for you to claim. Please use the following token to register:</p>
+      
+      <div style="text-align: center;">
+        <span class="token">{{inviteToken}}</span>
+      </div>
+      
+      <p>This token will expire on <strong>{{expirationDate}}</strong>.</p>
+      
+      <p>To create your account:</p>
+      <ol>
+        <li>Visit {{registrationUrl}}</li>
+        <li>Enter your email and create a password</li>
+        <li>When prompted, enter the token above</li>
+      </ol>
+      
+      <div style="text-align: center;">
+        <a href="{{registrationUrl}}" class="button">Create Your Account</a>
+      </div>
+      
+      <p>If you have any questions, 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}} {{clinicName}}. All rights reserved.</p>
+    </div>
+  </div>
+</body>
+</html>
+`;

package/src/services/README.md

@@ -0,0 +1,106 @@
+# Services
+
+This directory contains service modules that implement the business logic of the application. Services act as an intermediary layer between the API handlers and data models, encapsulating complex operations and enforcing business rules.
+
+## Service Responsibilities
+
+Services handle:
+
+1. **Business Logic**: Implementing complex business rules and workflows
+2. **Data Validation**: Ensuring data integrity before persistence
+3. **Transaction Management**: Handling atomic operations across multiple entities
+4. **Error Handling**: Providing consistent error responses for business logic failures
+5. **Integration**: Coordinating interactions with external services and APIs
+
+## Service Structure
+
+Each service typically follows this pattern:
+
+```typescript
+// Service function signature
+export const someServiceFunction = async (
+  params: SomeParamsType,
+  options?: SomeOptionsType
+): Promise<SomeReturnType> => {
+  try {
+    // 1. Input validation
+    const validatedData = someSchema.parse(params);
+
+    // 2. Business logic implementation
+    // ...
+
+    // 3. Data persistence
+    const result = await saveToDatabase(processedData);
+
+    // 4. Return formatted response
+    return result;
+  } catch (error) {
+    // Error handling and transformation
+    if (error instanceof z.ZodError) {
+      throw new ValidationError("Invalid input data", error);
+    }
+    // Other error handling...
+    throw error;
+  }
+};
+```
+
+## Core Services
+
+The application includes the following service modules:
+
+- **auth**: User authentication and authorization
+- **user**: User profile management
+- **practitioner**: Practitioner profile and availability management
+- **clinic**: Clinic/facility management
+- **procedure**: Medical procedure and service management
+- **appointment**: Appointment scheduling and management
+- **review**: Practitioner review and rating
+- **search**: Search functionality across entities
+- **notification**: User notification delivery
+- **file**: File upload and management
+
+## Error Handling
+
+Services use a consistent error handling approach:
+
+- Custom error types for different failure scenarios
+- Error transformation to provide meaningful context
+- Detailed error information for debugging while maintaining security
+
+## Transaction Management
+
+For operations affecting multiple entities, services implement transaction patterns to ensure data consistency:
+
+```typescript
+// Example transaction pattern
+export const complexOperation = async (data: SomeType): Promise<ResultType> => {
+  // Begin transaction context
+  try {
+    // Multiple database operations...
+
+    // If all succeed, return result
+    return result;
+  } catch (error) {
+    // Handle error and ensure rollback if needed
+    throw error;
+  }
+};
+```
+
+## Service Dependencies
+
+Services may depend on other services to complete their operations. Dependencies are typically:
+
+- Explicitly imported at the module level
+- Passed as parameters to functions when needed for testing
+- Designed to avoid circular dependencies
+
+## Testing
+
+Services are designed to be easily testable:
+
+- Pure functions where possible
+- External dependencies injectable for mocking
+- Clear input/output contracts
+- Isolated business logic