@blackcode_sa/metaestetics-api 1.5.29 → 1.5.30

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

package/src/services/clinic/README.md

@@ -0,0 +1,87 @@
+# Clinic Service
+
+This service manages clinic data within the Firestore database. It provides methods for creating, reading, updating, and managing clinics, their branches, and associated data like tags and administrators.
+
+**Note:** This service relies on helper functions defined in the `./utils` directory for specific operations like photo uploads, geo-queries, and data fetching. Cloud Functions handle data aggregation into related entities (Practitioners, Procedures, ClinicGroups).
+
+## `ClinicService` Class
+
+Extends `BaseService`.
+
+### Constructor
+
+```typescript
+constructor(
+  db: Firestore,
+  auth: Auth,
+  app: FirebaseApp,
+  clinicGroupService: ClinicGroupService,
+  clinicAdminService: ClinicAdminService
+)
+```
+
+Initializes the service with Firestore, Auth, App instances, and required dependency services (`ClinicGroupService`, `ClinicAdminService`).
+
+### Core Methods
+
+- **`createClinic(data: CreateClinicData, creatorAdminId: string): Promise<Clinic>`**
+  - Creates a new clinic document in Firestore.
+  - Validates input data using `createClinicSchema`.
+  - Verifies the `creatorAdminId` and their association with the specified `clinicGroupId`.
+  - Calculates the geohash for the clinic's location.
+  - Initializes default review information.
+  - Handles photo uploads for logo, cover photo, featured photos, and photos with tags using utility functions.
+  - Updates the creator admin's `clinicsManaged` list.
+  - **Aggregation Note:** Adding the clinic to the `ClinicGroup` is handled by Cloud Functions.
+- **`updateClinic(clinicId: string, data: Partial<Omit<Clinic, \"id\" | \"createdAt\" | \"clinicGroupId\">>, adminId: string): Promise<Clinic>`**
+  - Updates an existing clinic document.
+  - Fetches the current clinic data.
+  - Validates the partial update data against the `clinicSchema` after merging with existing data.
+  - Updates the geohash if the location is changed.
+  - Handles photo updates/uploads if necessary.
+  - **Aggregation Note:** Aggregation updates in related entities (Practitioners, Procedures, ClinicGroup) are handled by Cloud Functions.
+- **`deactivateClinic(clinicId: string, adminId: string): Promise<void>`**
+  - Sets the `isActive` flag of a clinic to `false`.
+  - Requires admin permission (verification logic might be in the calling function or assumed).
+  - **Aggregation Note:** Aggregation updates (e.g., removing from active lists, updating related entities) are handled by Cloud Functions.
+- **`getClinic(clinicId: string): Promise<Clinic | null>`**
+  - Retrieves a single clinic document by its ID using `ClinicUtils.getClinic`.
+- **`getClinicsByGroup(groupId: string): Promise<Clinic[]>`**
+  - Retrieves all clinic documents belonging to a specific `clinicGroupId` using `ClinicUtils.getClinicsByGroup`.
+- **`findClinicsInRadius(center: { latitude: number; longitude: number }, radiusInKm: number, filters?: { procedures?: string[]; tags?: ClinicTag[] }): Promise<Clinic[]>`**
+  - Finds active clinics within a specified radius using geohash queries.
+  - Leverages `SearchUtils.findClinicsInRadius`.
+  - Optionally filters results by procedure IDs (services) and tags.
+- **`addTags(clinicId: string, adminId: string, newTags: { tags?: ClinicTag[] }): Promise<Clinic>`**
+  - Adds specified tags to a clinic's `tags` array using `TagUtils.addTags`.
+  - Ensures the admin has permission. Prevents duplicates.
+- **`removeTags(clinicId: string, adminId: string, tagsToRemove: { tags?: ClinicTag[] }): Promise<Clinic>`**
+  - Removes specified tags from a clinic's `tags` array using `TagUtils.removeTags`.
+  - Ensures the admin has permission.
+- **`getClinicsByAdmin(adminId: string, options?: { isActive?: boolean; includeGroupClinics?: boolean }): Promise<Clinic[]>`**
+  - Retrieves clinics associated with a specific admin using `ClinicUtils.getClinicsByAdmin`.
+  - Handles options for filtering by `isActive` and including all group clinics for owners.
+- **`getActiveClinicsByAdmin(adminId: string): Promise<Clinic[]>`**
+  - Retrieves only the active clinics associated with a specific admin using `ClinicUtils.getActiveClinicsByAdmin`.
+- **`createClinicBranch(clinicGroupId: string, setupData: ClinicBranchSetupData, adminId: string): Promise<Clinic>`**
+  - Creates a new clinic (branch) within an existing `clinicGroupId`.
+  - Validates group existence. Uses `createClinic` internally.
+- **`getClinicById(clinicId: string): Promise<Clinic | null>`**
+  - Retrieves a single clinic document by its ID using `ClinicUtils.getClinicById`.
+- **`getAllClinics(pagination?: number, lastDoc?: any): Promise<{ clinics: Clinic[]; lastDoc: any }>`**
+  - Retrieves all clinics, ordered by ID, optionally with pagination, using `ClinicUtils.getAllClinics`.
+- **`getAllClinicsInRange(center: { latitude: number; longitude: number }, rangeInKm: number, pagination?: number, lastDoc?: any): Promise<{ clinics: (Clinic & { distance: number })[]; lastDoc: any }>`**
+  - Retrieves all clinics within a range, sorted by distance, optionally with pagination, using `ClinicUtils.getAllClinicsInRange`.
+- **`getClinicsByFilters(filters: { ... }): Promise<{ clinics: (Clinic & { distance?: number })[]; lastDoc: any }>`**
+  - Retrieves clinics based on complex filters (location, tags, procedures, rating, etc.).
+  - Uses `FilterUtils.getClinicsByFilters` for combined query and in-memory filtering.
+
+### Utility Functions (`./utils`)
+
+- **`clinic.utils.ts`**: Core fetching (`getClinic`, `getClinicsByGroup`, etc.), create/update/deactivate logic wrappers, admin checks.
+- **`filter.utils.ts`**: Complex filtering logic (`getClinicsByFilters`), including geo-queries.
+- **`clinic-group.utils.ts`**: Helpers for clinic group interactions (used by `ClinicGroupService`).
+- **`tag.utils.ts`**: Logic for adding/removing tags (`addTags`, `removeTags`).
+- **`photos.utils.ts`**: Firebase Storage interactions (`uploadPhoto`, `uploadMultiplePhotos`, `deletePhoto`).
+- **`admin.utils.ts`**: Helpers for clinic admin interactions (used by `ClinicAdminService`).
+- **`search.utils.ts`**: Geo-radius search logic (`findClinicsInRadius`).